̰

Overview

Freshchat is a cloud based messaging solution that allows you to effectively interact with your business users. It provides an efficient messaging service for lead generation, customer engagement, and customer support and thereby, makes your business competent.

Freshchat APIs can be used by customers and partners to build custom integrations and workflows. APIs help solve the problems around customising existing workflows and tailoring it to specific business structures, integrating bot flows into messaging, syncing-up and transferring data from external systems, and so on.

Status and error messages

Freshchat uses the standard HTTP status codes to indicate the success, in-progress, or failure states of an API request. The standard HTTP status codes used by Freshchat are as follows:

HTTP Status Code Message
200 Success Request
202 Accepted
400 Bad Request
401 Unauthenticated Request
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Request
503 Service Unavailable

A successful request returns a response object along with the 200 Success Request status message.
A 202 Accepted status message indicates that the request is being processed.
The 500 Internal Server Request and 503 Service Unavailable status codes indicate that there is an unexpected error caused from the Freshchat side.

Response message

An API request returns an object as the response.
Example 1
1
2
3
4
5
6
{
    "code":202,
    "status":"ACCEPTED",
    "message":"Agent deletion request accepted",
}
Example 2
1
2
3
4
5
6
{
    "code":404,
    "status":"AGENT_NOT_FOUND",
    "message":"agent not found",
}

Attributes
Attribute Name Data Type Description
code integer HTTP status code.
status string Default HTTP status message associated with the code.
message string Message specific to Freshchat, stating the results of the API request.

Header Parameters

The common request header parameters that are used in the requests to the Freshchat APIs are,

  • Accept
  • Authorization
  • Content-Type

Accept

Specifies the accepted format of response. The header parameter is used in the API requests that are intended to return a response body.

Header parameter format

Accept: application/<format>

<format> is typically JSON and a parameter value of application/JSON specifies that the response must be a JSON object.
A parameter value of */* specifies that data of any type is acceptable as the response.

Authorization

Specifies the credentials required to authenticate and authorize an API call.

Header parameter format

Authorization: Bearer <access-token>

<access-token> is the value returned by a request call to the authentication server.

Content-Type

Specifies the format in which data is sent in the request body to the recipient.

Header parameter format

Content-Type: application/<format>

<format> is typically JSON and a parameter value of application/JSON specifies that the request body is a JSON object.

Content-Type: multipart/<format>

<format> is typically form-data and a parameter value of multipart/form-data specifies that the request body contains key-value pairs that represent form fields and values. It is used for file uploads.

Authentication and Authorization

Freshchat uses Oauth 2.0 for authentication and authorization and the process involves the following steps,

  1. Make a call to the Freshchat authentication server from the Freshchat user interface, to obtain an access token (API key).
  2. Use the API Key in further API requests, to make valid API calls.

In the Oauth 2.0 authentication scheme, the access token (API key) identifies the requester and defines the permissions for the requester. Each token has a defined lifetime.

If you send a request with an expired token, the request fails with the 401 Unauthenticated Request error message. You can obtain another token from the authentication server and retry the request with the latest token.

Retrieve the API key

To obtain the API key, navigate to Admin > CONFIGURE > API Tokens page and click the Generate Token button. The authentication server returns the access token (specified in the page as API KEY). You should use the API key in the authorization header parameter to make a valid API call.

For a built-in chat account that is available as part of the Freshsales Suite product (Example account URL: https://.myfreshworks.com), to obtain the API key, navigate to Settings > Admin Settings > Website Tracking and APIs > API Settings. The API Settings page is displayed. In the API DETAILS FOR CHAT section, in the Your API Key field, the API key (access token) is displayed.

Note: If the API key (access token) is unavailable, click Generate token displayed adjacent to the Your API Key field. The authentication server returns the API key.

Retrieve the account URL

For stand-alone Freshchat accounts, the URL to access the product resources, through API requests, is of the following format:

https://<account-name>.freshchat.com/v2/<resource-name>

Example:

https://freshfoods.freshchat.com/v2/conversations

For a Freshchat account that is built-in and available as part of the Freshsales Suite account, to retrieve the actual account URL and use it in API requests, navigate to Settings > Admin Settings > Website Tracking and APIs > API Settings. The API Settings page is displayed. In the API DETAILS FOR CHAT section, in the Your chat URL field, the URL is displayed. The full URL to access the product resources, through API requests, is of the following format:

https://<retrieved-account-url>/<resource-name>

Example:

https://freshfoods-007-1234.myfreshworks.com/v2/conversations

Rate Limits

The number of API calls permitted (on an hourly basis) is specific to a business account and varies depending on the Freshchat plan that the business uses. The following parameters in the response header help to track the rate limits:

Parameter Name Description
X-RateLimit-Limit Specifies the total number of API calls permissible in a timeframe.
X-RateLimit-Remaining Specifies the number of API calls remaining in the timeframe.
X-RateLimitReset Specifies the time remaining to reset the previously set time.

Accounts

An organization can have multiple accounts configured within the Freshworks ecosystem. Account information identifies an account and entails other miscellaneous configuration details pertaining to the account. You can use the Account API to access and work with the account information.

Endpoints

GET /accounts/configuration

The accounts object

Example 
1
2
3
4
5
6
7
8
9
10
11
{
                "organisation_id": 1775382926361,
                "organisation_domain": "example.freshworks.com",
                "account_id": 8762573821,
                "account_domain": "example.freshchat.com",
                "app_id": "9d83ebc5-e036-4b48-b655-b0d79584b2c5",
                "bundle_id": 991773928113,
                "bundle_type": "support360",
                "plan_type": "Enterprise Annual Plan 2021",
                "datacenter": "US"
    }
EXPAND ↓
Attributes
Attribute Name Data Type Description
organisation_id integer Unique Identifier of an organization, auto-generated when the organization is configured in the Freshworks system.
organisation_domain string Full domain name of the organisation.
account_id integer Unique identifier for the Freshchat account whose account information is retrieved. The account_id is auto-generated when an account is created.
account_domain string Domain name of the Freshchat account whose account information is retrieved by using the account API.
app_id string Organizations that use Freshchat are assigned an app_id that can be used to integrate an application with Freshchat. To obtain the app_id, navigate to https://web.freshchat.com and log in with the corresponding account credentials. Navigate to Settings > Account Settings > Integration Settings. The app_id is displayed under AGENT WIDGET.
bundle_id integer Bundle refers to the group of products extended to an organization from the Freshworks ecosystem. bundle_id is the unique identifier of the bundle to which the Freshchat account belongs.

Note: If the account is not available as part of a bundle, the bundle_id value is 0.
bundle_type string Type of the bundle to which the Freshchat account belongs. It indicates whether the account uses Freshchat as a stand-alone product or as part of a bundle.

Possible values: freshchat, sales 360, and support360.
plan_type string Organization’s subscription plan that specifies whether the account is a Free, Growth, Pro or Enterprise account.
datacenter string Datacenter where the Freshchat account is deployed.

Possible values: US, EUC, AUS, IND and US2.

Retrieve account information

Retrieves information pertaining to the account configured for an organization, in the Freshchat system.

get
/v2/accounts/configuration
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
curl -X GET \
      https://example.freshchat.com/v2/accounts/configuration\
      -H 'accept: application/json'
      -H 'Authorization: Bearer eyJraWQiOiJjdXN0b20tb2F1dGgta2V5aWQiLCJ0eXxxxxxxxxxxisXh3E4cX8tY' \
      -H 'content-type: application/json'
      --data-raw
EXPAND ↓
Response

A successful request returns a 200 OK along with the retrieved accounts object.

Users

Users are an organization’s customers who use Freshchat to converse with the organization.

Endpoints

POST /users
GET /users
POST /users
POST /users/fetch
GET /users/{user_id}
PUT /users/{user_id}
DELETE /users/{user_id}

The user object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{ 
		"id": "ca03d5ea-9615-4069-8938-bc39e522a436",
		"created_time": "2022-08-29T07:32:07.003Z",
		"updated_time": "2022-10-27T12:30:39.591Z"
		"avatar": {
	  		"url":"https://fc-pics.s3.amazonaws.com/img/johndoe.png"
		 },
		"email": "alice.john@email.com",
		"first_name": "Alice",
		"last_name": "John",
		"login_status": false,
		"org_contact_id": " ",
		"phone": "174285396",
		"properties": [
			{
				"name": "fc_user_timezone",
				"value": "Asia/Calcutta"
			},
			{
				"name": "siteId",
				"value": "213123"
			}
		],
		"reference_id": "121",
		"restore_id": "0663d5f0-f6cc-43f6-bd74-e5d0c0e2cf09"
	  }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the user object, auto-generated when a user record is created in the Freshchat system.
created_time string Timestamp of when the user record is created in the Freshchat system, specified in the UTC format.
updated_time string Timestamp of when the user details are last updated in the Freshchat system, specified in the UTC format.
avatar object Image used as the display picture in the user’s profile.
Attributes of the object:
url (string): Link from which the image is fetched.
email string Email address of the user.
first_name string First name of the user.
last_name string Last name of the user.
login_status boolean Specifies whether the user is logged into the Freshchat system.
Possible values: true, false
org_contact_id string Organization-level identifier of the user.
phone string Phone number of the user.
properties array of objects Additional user information. This attribute contains custom property names and the corresponding values, as a valid JSON object of name (custom property name)-value (custom property’s value) pairs.
ttributes of the object:
name (string): Name of the custom property.
value (string): Value of the custom property.
reference_id string User identifier that the system sets for a user when Freshchat is integrated with our Customer Experience suite of products.
restore_id string Unique identifier of the user, auto-generated when a conversation is initiated in the Freshchat system. When a logged-in user uses a new device or browser to initiate a conversation, restore_id identifies the user and restores the past conversations.
This attribute value is returned as part of the response to the create a user API call.

List users by specified criteria

Retrieves a list of all the users who meet a specific search query.

get
/v2/users
Query parameters

You can use a combination of the following query parameters and pagination parameters to retrieve the appropriate set of users. Ensure that the query parameter values are URL encoded.

Note: At least one of the following query parameters is mandatory for a successful response.

Parameter Name Description Example
first_name Limits the response to user objects whose first_name value matches the parameter value.

GET /users?first_name=Alice
last_name Limits the response to user objects whose last_name value matches the parameter value.

GET /users?last_name=Doe
email Limits the response to user objects whose email value matches the parameter value.

GET /users?email=alice.doe@mail.com
reference_id Limits the response to user objects whose reference_id value matches the parameter value.

GET /users?reference_id=121
phone_no Limits the response to user objects whose phone_no value matches the parameter value.

GET /users?phone_no=639528417
created_from

Should be a date-time value specified in the UTC format.		 Limits the response to user objects whose created_time value is a time after the parameter value or matches the parameter value.

GET /users?created_from=2022-10-13T09:03:34.709Z
created_to

Should be a date-time value specified in the UTC format.		 Limits the response to user objects whose created_time value is a time before the parameter value.

GET /users?GET /users?created_to=2022-10-13T09:03:34.709Z
updated_from

Should be a date-time value specified in the UTC format.		 Limits the response to user objects whose updated_time value is a time after the parameter value.

GET /users?updated_from=2022-10-27T12:25:15.831Z
updated_to

Should be a date-time value specified in the UTC format.		 Limits the response to user objects whose updated_time value is a time before the parameter value.

GET /users?updated_to=2022-10-27T12:25:15.831Z
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/users?first_name=Alice&page=1&items_per_page=100&sort_order=asc&sort_by=email" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJraxxxdQ"
EXPAND ↓
Response

A successful request returns 200 OK along with all users’ details, as an array. Each array entry is a user object with the corresponding attributes. The response data is limited by the query and pagination parameters passed in the request. The response also contains response parameters pertaining to pagination.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
    "users": [
        {
            "properties": [
                {
                    "name": "fc_user_timezone",
                    "value": "Asia/Calcutta"
                }
            ],
            "reference_id": "random123@random.com",
            "restore_id": "d323efcb-1a2e-4ccc-96d0-cb0791481f61",
            "created_time": "2022-10-13T09:03:34.709Z",
            "updated_time": "2022-10-27T12:25:15.831Z",
            "id": "2079f4e7-e608-43d9-acb1-593908ca5426",
            "first_name": "Alice",
            "last_name": "Doe",
            "email": "alice.doe@mail.com",
            "avatar": {},
            "phone": "639528417",
            "login_status": false
          },
          {
            "properties": [
                {
                    "name": "fc_user_timezone",
                    "value": "Asia/Calcutta"
                },
                {
                    "name": "siteId",
                    "value": "213123"
                }
            ],
            "reference_id": "121",
            "restore_id": "0663d5f0-f6cc-43f6-bd74-e5d0c0e2cf09",
            "created_time": "2022-08-29T07:32:07.003Z",
            "updated_time": "2022-10-27T12:30:39.591Z",
            "id": "ca03d5ea-9615-4069-8938-bc39e522a436",
            "first_name": "Alice",
            "last_name": "John",
            "email": "alice.john@email.com",
            "avatar": {},
            "phone": "174285396",
            "login_status": false
        }
    ],
    "pagination": {
        "total_items": 4,
        "total_pages": 1,
        "current_page": 1,
        "items_per_page": 100
    },
    "links": {
        "first_page": {
            "href": "/v2/users?first_name=Alice&items_per_page=100&sort_order=asc&sort_by=email&page=1",
            "rel": "user",
            "type": "GET"
        },
        "last_page": {
            "href": "/v2/users?first_name=Alice&items_per_page=100&sort_order=asc&sort_by=email&page=1",
            "rel": "user",
            "type": "GET"
        }
    }
}
EXPAND ↓

List a subset of users

Identifies users by the user.ids specified in the request body and retrieves the users’ details, as an array of user objects.

Note: A maximum of 100 user’s details can be retrieved using this API.

post
/v2/users/fetch
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
curl -X POST "https://<account>.freshchat.com/v2/users/fetch"
    -H "accept: application/json" 
    -H "Authorization: Bearer eyJraxxxdQ" 
    -H "Content-Type: application/JSON" 
    -d "{
      'ids': [
        '2079f4e7-e608-43d9-acb1-593908ca5426',
        '2deb2a22-703e-4f1d-8527-7bd123c84fd4'
      ]
    }"
EXPAND ↓
The request body parameter
Example 
1
2
3
4
5
6
{
    "ids": [
        "2079f4e7-e608-43d9-acb1-593908ca5426",
        "2deb2a22-703e-4f1d-8527-7bd123c84fd4"
    ]
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
ids array of strings Identifiers of the user objects that must be retrieved.
The user.id value is auto-generated when a user record is created in the Freshchat system.
Response

A successful request returns 200 OK along with the retrieved users’ details, as an array. Each array entry is a user object with the corresponding attributes.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "users": [
        {
            "id": "2079f4e7-e608-43d9-acb1-593908ca5426",
            "created_time": "2022-10-13T09:03:34.709Z",
            "updated_time": "2022-10-27T12:25:15.831Z"
            "avatar": {},
            "email": "alice.doe@mail.com",
            "first_name": "Alice",
            "last_name": "Doe",
            "login_status": false,
            "phone": "639528417",
            "reference_id": "random123@random.com"
        },
        {
            "id": "2deb2a22-703e-4f1d-8527-7bd123c84fd4",
            "created_time": "2022-10-31T00:56:40.218Z",
            "updated_time": "2022-10-31T10:22:52.190Z"
            "avatar": {
                "url": "https://web.freshchat.com/img/johndoe.png"
            },
            "email": "milton.doe@mail.com",
            "first_name": "Milton",
            "last_name": "Doe",
            "login_status": false,
            "phone": "1234567890",
            "reference_id": "milton@doe",
            "restore_id": "2dd06fc0-a48c-4f48-bf7a-ca1ec164a7a0"
        }
    ]
}
EXPAND ↓

Retrieve user information

Identifies a user by the user_id passed in the request and returns the corresponding information as a user object.

get
/v2/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory string Identifier of the user object, auto-generated when a user record is created in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/users/2deb2a22-703e-4f1d-8527-7bd123c84fd4" 
	-H "accept: application/json"  
	-H "Authorization: Bearer eyJraxxxdQ"
EXPAND ↓
Response

A successful request returns 200 OK along with the retrieved user object.

Create a user

Creates a user object based on the information in the request body. The request body parameter should be a valid JSON object of the specified format.

post
/v2/users
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
curl -X POST "https://<account>.freshchat.com/v2/users"
    -H "accept: application/json" 
    -H "Authorization: Bearer eyJraxxxdQ" 
    -H "Content-Type: application/JSON" 
    -d "{
            'avatar': {
                'url': 'https://web.freshchat.com/img/johndoe.png'
            },
            'email': 'milton.doe@mail.com',
            'first_name': 'Milton',
            'last_name': 'Doe',
            'phone': '235689714',
            'properties': [
                {
                    'name': 'orderId',
                    'value': '#1242'
                }
            ],
            'reference_id': 'milton@doe'
      }"
EXPAND ↓
The request body parameter
Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "avatar": {
        "url": "https://web.freshchat.com/img/johndoe.png"
    },
    "email": "milton.doe@mail.com",
    "first_name": "Milton",
    "last_name": "Doe",
    "phone": "235689714",
    "properties": [
        {
            "name": "orderId",
            "value": "#1242"
        }
    ],
    "reference_id": "milton@doe"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
avatar object Image used as the display picture in the user’s profile.
Attributes of the object:
url (string): Link from which the image is fetched.
email string Email address of the user.
first_name string First name of the user.
last_name string Last name of the user.
phone string Phone number of the user.
properties array of objects Custom properties for additional user information. This attribute contains custom property names and the corresponding values, as a valid JSON object of name(custom property name)-value (custom property’s value) pairs.
Attributes of the object:
name (string): Name of the custom property.
value (string): Value of the custom property.
reference_id string User identifier that the system sets for a user when Freshchat is integrated with our Customer Experience suite of products.
Response

A successful request returns 201 Created along with the created user object. The object contains the id, created_at, updated_at, and restore_id attributes. In further API calls, the id that is returned can be used to update the corresponding user information or retrieve further information.

Update user information

Identifies a user object by the user_id passed in the request and updates the object with the information specified in the request body. The request body parameter should be a valid JSON object of the specified format. If an attribute value is null or not passed as part of the request payload, the attribute’s existing value is retained.
Note: Only the values of the attributes email, first_name, last_name, and phone can be updated using this API.

put
/v2/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory string Identifier of the user object, auto-generated when a user record is created in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
curl -X PUT "https://<account>.freshchat.com/v2/users/2deb2a22-703e-4f1d-8527-7bd123c84fd4" 
    -H "accept: application/JSON" 
    -H "authorization: Bearer eyJraxxxdQ" 
    -H "content-type: application/JSON" 
    -d "{
    'email': 'milton.doe@mail.com', 
    'avatar': {
         'url': 'https://web.freshchat.com/img/johndoe.png'
    }, 
    'phone': '1234567890',
    'org_contact_id': 'abcd12345', 
    'restore_id': ' ', 
    'properties': [{ 
    'name': 'orderId', 
    'value': '#1242' 
    }], 
    'reference_id': 'milton@doe',
    'first_name': 'Milton', 
    'last_name': 'Doe', 
    'social_profiles': [{ 
    'type': 'facebook', 
    'id': 'milton.doe'
    }]
    }"
EXPAND ↓
Response

A successful request returns 202 Accepted. You can use the Retrieve user information API to retrieve and view the updated values.

Retrieve all conversations for a user

Identifies a user by the user_id passed in the request and returns the list of all the conversations associated with the user.

get
/v2/users/{user_id}/conversations
Path parameters
Parameter Name Data Type Description
user_idMandatory string Identifier of the user object, auto-generated when a user record is created in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/users/16d1bcc2-803a-48f7-bb00-60558d b0b80e/conversations" 
    -H "accept: application/json" 
    -H "Authorization: Bearer eyJraxxxdQ"
EXPAND ↓
Response

A successful request returns 200 OK along with the retrieved conversation ids.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "conversations": [
        {
            "id": "59b838d2-f0ce-4a08-b037-4d8752c95bb3"
        },
        {
            "id": "317d8288-f770-4dd1-8e27-538a164c2d85"
        },
        {
            "id": "879dd410-7340-4948-b24e-fb91515ee1d2"
        },
        {
            "id": "7aa70911-9631-4a81-9424-1a790c7df1aa"
        }
    ]
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the conversation object, auto-generated when a new conversation is created in the Freshchat system.

Delete a user

Identifies a user by the user_id passed in the request and permanently deletes the user’s record from the Freshchat system. The user details cannot be retrieved from the Freshchat system after this delete which primarily serves to meet General Data Protection Regulation (GDPR) requirements.

delete
/v2/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory string Identifier of the user object, auto-generated when an user’s information is stored in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
curl -X DELETE "https://<account>.freshchat.com/v2/users/ca03d5ea-9615-4069-8938-bc39e522a436" 
    -H "accept: application/json" 
    -H "Authorization: Bearer eyJraxxx7odQ"
EXPAND ↓
Response

A successful request returns 202 Accepted along with the following response.

Example 
1
2
3
4
5
6
7
8
{
    "id":"ca03d5ea-9615-4069-8938-bc39e522a436",
    "link":{
        "rel":"self",
        "href":"/users/ca03d5ea-9615-4069-8938-bc39e522a436",
        "type":"GET"
    }
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the user object that is to be deleted.
link object Reference to the object being deleted; this reference can be used to construct another API call and verify the deletion status.
Attributes of the object:
rel (string): Relation to the hypertext reference specified as the href value.
href (string): Hypertext reference to verify the deletion status.
type (string): Type of call that must be used when constructing the API call to verify deletion status.

Conversations

Freshchat facilitates interactions between an organization and its end-user. These interactions are recorded as conversations. Agents and users can initiate conversations and subsequently send messages to conversations. Agents and bots can handle conversations. Conversations can be auto-assigned or manually assigned to a group or agent.

When an agent or a bot sends a message to a conversation, the message can contain response enablers such as - quick reply buttons, urls, carousel cards, drop-downs and so on. For information on how to construct such a message, see the message part object.

Conversation properties [Valid only for built-in chat accounts that are available as part of Freshsales Suite]: Conversation properties is a widget that contains important information pertaining to a conversation. All built-in chat accounts that are available as part of Freshsales Suite, come with the following default fields configured for the Conversation properties widget: group, agent, status, and priority. Apart from these fields, admins can configure custom Conversation properties fields. The fields can be pre-populated with data to ensure correct assignment to agent/groups or the agents working on the conversation can populate the fields during the course of the conversation resolution. Chatbots can collect information from end-users and prepopulate the widget fields; businesses can pre-populate the fields based on available context. For more information, see Conversation properties. The List all conversation properties API can be used to retrieve all Conversation properties fields that are configured for an account.

Endpoints

POST /conversations
GET /conversations/{conversation_id}
PUT /conversations/{conversation_id}
GET /conversations/{conversation_id}/messages
POST /conversations/{conversation_id}/messages
GET /conversations/fields

The conversation object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
	"conversation_id": "83dd2824-7090-4a10-877d-863f394c610f",
	"channel_id": "71df7c11-df1e-4365-80e3-75a434c9caf0",
	"assigned_org_agent_id": "462153445185974756",
	"assigned_agent_id": "1ad50c45-050b-4702-9300-478ddcf23c65",
	"assigned_org_group_id": "",
	"assigned_group_id": "e769cd13-0cd3-4d64-81ac-32657642a24d",
	"messages": [
		{
			"message_parts": [
				{
					"text": {
						"content": "Hii! Need help in receiving the refund."
					}
				}
			],
			"app_id": "1c4dabcf-61d5-4490-b1a5-d3ff62c8e664",
			"actor_id": "86a76727-f5f7-40b5-8f93-309043646b1c20230415141608",
			"org_actor_id": "1647242406397890560",
			"id": "16bb7d43-d50e-48c9-b82a-80137a280d99",
			"channel_id": "71df7c11-df1e-4365-80e3-75a434c9caf0",
			"conversation_id": "83dd2824-7090-4a10-877d-863f394c610f",
			"interaction_id": "746122323012625-1684913970239",
			"message_type": "normal",
			"actor_type": "user",
			"created_time": "2023-05-24T07:39:30.239Z",
			"user_id": "86a76727-f5f7-40b5-8f93-309043646b1c20230415141608",
			"restrictResponse": false,
			"botsPrivateNote": false
		}
	],
	"app_id": "1c4dabcf-61d5-4490-b1a5-d3ff62c8e664",
	"status": "new",
	"skill_id": 0,
	"properties": {
		"priority": "Low",
		"cf_type": "General Query",
		"cf_rating": "5"
	},
	"users": [{ 
		"id": "86a76727-f5f7-40b5-8f93-309043646b1c20230415141608"
	}]
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
conversation_id string Identifier of the conversation object, auto-generated when a conversation record is created in the Freshchat system.
channel_id string Identifier of the topic under which the conversation is created, auto-generated when a topic is created in the Freshchat system.
assigned_agent_id string Identifier of the agent to whom the conversation is assigned for resolution.
The value of assigned_agent_id is a valid agent.id, auto-generated when an agent information is created in the Freshchat system.
assigned_org_agent_id string Organization-level identifier of the agent to whom the conversation is assigned for resolution.
assigned_group_id string Identifier of the group to which the conversation is assigned for resolution.
The value of assigned_group_id is a valid group.id, auto-generated when a group is configured in the Freshchat system.
assigned_org_group_id string Organization-level identifier of the group to which the conversation is assigned for resolution.
messages array of message objects Details of the messages that constitute the conversation.
app_id string Auto-assigned organization-level identifier that helps integrate applications with Freshchat.
status string Status of the conversation.
Possible values: new, assigned, resolved, reopened
skill_id
Internal attribute		 integer -
properties
VALID ATTRIBUTE ONLY FOR CHAT ACCOUNTS AVAILABLE AS PART OF THE FRESHSALES SUITE		 object

Details of the conversation properties configured for the Freshchat account. The attribute contains the names of the conversation properties configured and the corresponding values populated, as a valid JSON object of key - value pairs.

Note: The properties attribute contains the default conversation property priority (which is preconfigured in the Freshchat system) and custom conversation properties (if an admin configures them in the Freshchat system). The custom conversation properties are identified by the prefix cf_ to their names.

The valid values of the properties.priority attribute are Low, Medium, High, and Urgent.
users
Mandatory attribute in the request body parameter; not retrieved as part of the response object.		 array of objects Identifier of the user who is associated with the conversation.
Attribute of the object:
id (string): Auto-generated identifier of the user with whom the conversation is initiated.

The message object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
"messages": [{
	"message_parts": [{
			"text": {
	 			"content": "For further information, check out Freshchat API documentation."
			} 
		}],
	"reply_parts": [{
		"collection": {
			"sub_parts": [{
					"url_button": {
						"url": "https://developers.freshchat.com/api/",
						"label": "Click for API documentation",
						"target": "_blank"
					}
				}
			]
		}
	}],
	"channel_id": "b0247bdb-2796-4489-bd0a-09c22b5440dc",
	"actor_type": "agent",
	"actor_id": "1de5d130-1c62-48cf-8349-1b39c60d0c28"
	}
]
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the message object, auto-generated when a new message is successfully sent to a conversation.
created_time string Timestamp of when the message is created, specified in the UTC format.
message_parts array of message part objects Different parts of a message posted to the conversation. For example, plain text, images, url buttons, collection of url buttons, and so on. The message can be a combination of these attributes.
reply_partsVALID ONLY WHEN MESSAGE_PARTS IS PRESENT array of message part objects The message an agent or bot posts to a conversation can contain segments (response enablers) that enable a user to respond to the message. The reply_parts attribute contains these segments. The segments can be a templated message (carousel cards or drop-down values) or a collection of url buttons and quick reply buttons.
app_id string Auto-assigned organization-level identifier that helps integrate applications with Freshchat.
actor_typeMandatory attribute in the request body parameter string Type of the entity who sent the message to the conversation.

Possible values: user, agent, bot, system
actor_idMandatory attribute in the request body parameter if the value of message.actor_type is user or agent. string Identifier of the entity who sends the message to the conversation.
If a user sends the message, the value of this attribute is a valid user.id. If an agent sends the message, the value of this attribute is a valid agent.id.

Note: If a Freshchat bot sends the message, the attribute will not have a valid value.
org_actor_id string Organization-level identifier of the entity who sends the message to the conversation.
channel_id string Identifier of the topic under which the message is created, auto-generated when a topic is created in the Freshchat system.
conversation_id string Identifier of the conversation which includes the message, auto-generated when a conversation record is created in the Freshchat system.
interaction_id string Identifier of the interaction, auto-generated when a conversation is initiated by a user or an agent.
An interaction is a conversation from the time it is initiated to the time the conversation is resolved. If the conversation is reopened, a new interaction_id is assigned to the conversation.
message_type string Type of message sent to the conversation.
Possible values:
normal (string): Regular message sent by an agent or user to the conversation.
private (string): Private message sent to the conversation and not visible to the user.
system (string): System generated message sent to the conversation.
Default value: normal
user_id string Identifier of the user associated with a conversation, if actor_type is user.
meta_data object Meta information about the conversation, specified as <key>:<value> pairs.
Example: isReopen: true
This is meta information that specifies whether the conversation is a reopened conversation.
in_reply_to object Identifier of the response-enabler message to which this message is sent as a reply.
Attribute of the object:
message_id (string): Auto-generated identifier of the message that triggered a reply/response.
error_code integer If the message sent to a conversation fails to be added as part of the conversation, error_code is the HTTP code associated with the failure.
status string If the message sent to a conversation fails to be added as part of the conversation, status is the generic HTTP status associated with error_code.
error_message string If the message sent to a conversation fails to be added as part of the conversation, error_message is the Freshchat specific message specifying the reason for the error.
error_category string If the message sent to a conversation fails to be added as part of the conversation, error_category provides the high level reason for failure.
Possible values: ACCOUNT, INTEGRATION, USER, MESSAGE, COMMON, OTHER
restrictResponse boolean If bots are enabled to handle conversations, the bot flow can be configured to trigger specific actions that execute events. If the action is to resolve a conversation or stop a conversation, as part of this action, further responses from the user can be restricted.

If a bot is enabled for a conversation, restrictResponse specifies whether further responses are restricted after the bot resolves or stops a conversation.

Possible values: true, false
botsPrivateNote boolean If bots are enabled to handle conversations, the message from the bot can be set as private - meaning they serve to only collect information from the customer/website visitor.

botsPrivateNote specifies whether the message set through the bot builder is private. If the message is private, it is not visible to the end user.

Possible values: true, false

The message part object

Attributes
Attribute Name Data Type Description
file object Details of the file attached to a message in a conversation.
    Attributes of the object:
  • fileHash (string): Hash value that is used to ensure that the file is uncorrupted during transfer.
  • fileSource (string): Source from which the file is attached as part of the message sent to the conversation.
    Possible values: FRESHCHAT, FRESHBOTS
  • name (string): Name of the attached file.
  • url (string): Link to the location from where the attached file can be retrieved.
  • file_size_in_bytes (integer): Size of the attached file.
  • contentType (string): Media type/Format of the attached file. For example, text/plain, image/png, and so on.
  • file_extension (string): Type of the attached file. For example, .txt, .png, and so on.
text IN REQUESTS, VALID ONLY FOR MESSAGE_PARTS object Text part of the message posted to a conversation.
Attributes of the object:
content (string) MANDATORY: Actual content of the text message.
imageIN REQUESTS, VALID ONLY FOR MESSAGE_PARTS object Image part of the message posted to a conversation.
Attributes of the object:
url (string) MANDATORY: Link to the location from where the image can be retrieved.
videoIN REQUESTS, VALID ONLY FOR MESSAGE_PARTS object Details of the video file attached to a message in a conversation.
Attributes of the object:
url (string): Location of the video file.
content_type (string): Format of the attached video.
collection IN REQUESTS, MANDATORY FOR REPLY_PARTS WHEN THE RESPONSE ENABLER IS A COLLECTION OF URL OR QUICK REPLY BUTTONS object The message that an agent sends to a conversation can contain a response enabler that is a combination of url buttons and quick reply buttons.

In a request, the collection attribute can be a part of message_parts and reply_parts. In message_parts, the message an agent sends to the conversation can be a collection of url buttons. In reply_parts, the response enabler an agent sends to the conversation can be a collection of url and quick reply buttons.

Attribute of the object:
sub_parts (array of message part objects): Different parts of a collection posted to a conversation.
url_button object The message that an agent sends to a conversation can contain a hyperlinked button that helps a user to navigate to a webpage.

In a request, the url_button attribute can be a part of message_parts and reply_parts. In reply_parts, the response enabler that an agent sends to the conversation can be a collection of url_buttons.
The url_button attribute contains the different components of the hyperlinked button.

    Attributes of the object:
  • url (string) MANDATORY: The actual hyperlink that is accessed by clicking the corresponding label.
  • label (string): Text (in the message) that is used as the connector to the hyperlink.
  • target (string): Location where the link is opened.
    Possible values:
    _self: Link is opened within the conversation widget.
    _blank: Link is opened in a new tab.
    By default, _blank is the value of url_button.target.
quick_reply_buttonVALID ONLY FOR REPLY_PART

IN REQUESTS, MUST BE USED AS PART OF REPLY_PARTS.COLLECTIONS 		object

The response enabler an agent posts to the conversation can be a collection of quick reply buttons. The quick_reply_button attribute contains the different components of the button.

    Attributes of the object:
  • Custom_reply_text (string): Custom text that is used as reply text.
  • label (string) MANDATORY: Label on the button that is used to give a quick reply.
  • payload (string): Data that is passed to the Freshchat system when a user responds using the quick reply button.
  • display_order (string): In a collection of quick reply buttons, display order determines the order in which the buttons are displayed on the user’s chat interface.
  • type (string): Type of preconfigured quick reply button that performs specific tasks.
    Possible value: RESEND_OTP
template_content Valid only for reply_part object The response enabler an agent posts to the conversation can be a templated message such as a carousel or drop-down list. The template_content attribute helps compose such a message.

In a response object, the template_content attribute contains different segments of the templated response enabler posted to the conversation.

Attributes of the object:
type (string): Identifier of the type of templated message.
    Possible values:
  • carousel: A scrollable list of carousel cards are displayed as response enablers. The template_content.sections values are used to populate the carousel cards. See example 7 for reference.
  • carousel_card_default: A single carousel card is displayed as a response enabler. The template_content.sections values are used to populate the carousel card.
  • quick_reply_dropdown: A drop-down list is displayed as the response enabler. The template_content.sections values are used to populate the drop-down list. See example 8 for reference.
sections (array of objects): Segments of the carousel card or drop-down list.
    Attributes of the object:
  • name (string) MANDATORY: Title of the carousel card or drop-down list displayed in the conversation window.
  • parts (array of objects) MANDATORY: Segments of the carousel card or values for the drop-down list.
callback object In a conversation, the reply message can be a carousel card which has the callback attribute.
Attributes of the callback part object:
payload (string): Data that is passed to the Freshchat system when a user responds using the carousel card.
label (string): Text that is displayed on the button.
When bots send messages to conversations, they may send the following attributes that are used to construct appropriate response enablers. When such messages are retrieved using APIs, the following attributes are retrieved as part of the response.
Note: The following attributes are not supported for use in agent-messages to construct response enablers.
attachment_inputResponse attribute object In a bot message, if attachement_input is used, the attach icon is displayed to the user. This provides a mechanism for users to send attachments in their replies. A user can attach files, images, or videos.
In the response to a List messages in a conversation API call, the following child attributes are retrieved as part of bot-sent messages. They indicate that the attachment_input response enabler was sent to the user involved in the conversation.
  • fragmentType
  • contentType
  • content
  • position
  • translatedContent
  • sourceLang
  • destLang
  • inputType
    Possible values: FILE, IMAGE, VIDEO
referenceResponse attribute object In a bot message, if reference is used, a link to an appropriate FAQ article is displayed to the user.
In the response to a List messages in a conversation API call, the following child attributes are retrieved as part of bot-sent messages. They indicate that the reference response enabler was sent to the user involved in the conversation.
  • reference_id
  • placeholder_reference_id
  • label
text_inputResponse attribute object

In a bot message, if text_input is used, a text input box is displayed to the user. This provides a mechanism for users to input text that can be validated. Validations can be input-type checks or regex validations. Appropriate error messages can be displayed if the validation checks fail.

In the response to a List messages in a conversation API call, the following child attributes are retrieved as part of bot-sent messages. They indicate that the text_input response enabler was sent to the user involved in the conversation.
    Attributes of the object:
  • fragmentType
  • contentType
  • content
  • position
  • translatedContent
  • sourceLang
  • destLang
  • inputType
    Possible values: EMAIL, PHONE, NUMBER, TEXT, OTP, PHONE_WITH_COUNTRY_CODE
  • placeholderText
  • exampleText
  • validations (array of objects)
      Attributes of the object:
    • type
      Possible values: INPUT_TYPE_VALIDATION, REGEX_VALIDATION
    • validationErrorText
help_text object In a bot message, if help_text is used, a text message is displayed to the user along with the other response enablers such as quick replies or url buttons.
In the response to a List messages in a conversation API call, the following child attribute is retrieved as part of bot-sent messages. It indicates that help_text was sent to the user involved in the conversation.
content(string)
Example 1 - Message with an image, text, and url_button

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
"messages": [
    {
        "message_parts": [
            {
                "text": {
                    "content": "Click for more details!!"
                }
            },
            {
                "image": {
                    "url": "https://fc-xx-00.s3.xxws.com/f51/f_marketingpicFull/u_be5bb9xxxd/img_a7dxx3.png"
                }
            },
            {
                "url_button": {
                    "url": "https://www.freshworks.com/live-chat-software/",
                    "label": "Freshchat",
                    "target": "_self"
                }
            }],
        "channel_id": "b0247bdb-2796-4489-bd0a-09c22b5440dc",
        "actor_type": "agent",
        "actor_id": "1de5d130-1c62-48cf-8349-1b39c60d0c28"
    }
]
EXPAND ↓

The response enabler rendered is as follows:

Example 2 - Message with a reply part that contains a url_button

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
"messages": [
    {
        "message_parts": [
            {
                "text": {
                    "content": "For further information, check out Freshchat API documentation."
                } 
        }],
        "reply_parts": [
            {
                "collection": {
                    "sub_parts": [
                        { 
                            "url_button": {
                                "url": "https://developers.freshchat.com/api/",
                                "label": "Click for API documentation",
                                "target": "_blank"
                            }
                        }
                    ]
                }
            }
        ],
        "channel_id": "b0247bdb-2796-4489-bd0a-09c22b5440dc",
        "actor_type": "agent",
        "actor_id": "1de5d130-1c62-48cf-8349-1b39c60d0c28"
    }
]
EXPAND ↓

The response enabler rendered is as follows:

Example 3 - Message with a reply part that contains a collection of quick reply buttons

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
"messages": [
    {
        "message_parts": [{
            "text": {
                "content": "Click proceed for samples"
            }
        }],
        "reply_parts": [{
            "collection": {
                "sub_parts": [{
                    "quick_reply_button": {
                        "label": "Proceed"
                    }
                },
                {
                    "quick_reply_button": {
                        "label": "Decline"
                    }
                }]
            }
        }],
        "channel_id": "b0247bdb-2796-4489-bd0a-09c22b5440dc",
        "actor_type": "agent",
        "actor_id": "1de5d130-1c62-48cf-8349-1b39c60d0c28"
    }
]
EXPAND ↓

The response enabler rendered is as follows:

Example 4 - Template message with carousel cards

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
"messages": [
    {
        "message_parts": [{
            "text": {
                "content": "Choose one of the product"
            }
        }],
        "reply_parts": [{
            "template_content": {
                "type": "carousel",
                "sections": [{
                    "name": "carousel_title",
                    "parts": [
                        {
                            "text": {
                                "content": "Choose one of the products"
                            }
                        }
                    ]},
                        {
                            "name": "cards",
                            "parts": [{
                                "template_content": {
                                    "type": "carousel_card_default",
                                    "sections": [{
                                        "name": "hero_image",
                                        "parts": [{
                                            "image": {
                                                "url": "https://test-s3-local.s3.amazonaws.com/fd.jpg"
                                            }
                                        }]
                                    },
                                    {
                                        "name": "title",
                                        "parts": [{
                                            "text": {
                                                "content": "Freshdesk"
                                            }
                                        }]
                                    },
                                    {
                                        "name": "callback",
                                        "parts": [{
                                            "callback": {
                                                "payload": "Freshdesk selected",
                                                "label": "Select"
                                            }
                                        }]
                                    }]
                                }
                            },
                            {
                                "template_content": {
                                    "type": "carousel_card_default",
                                    "sections": [{
                                        "name": "hero_image",
                                        "parts": [{
                                            "image": {
                                                "url": "https://test-s3-local.s3.amazonaws.com/Fc.jpg"
                                            }
                                        }]
                                    },
                                    {
                                        "name": "title",
                                        "parts": [{
                                            "text": {
                                                "content": "Freshchat"
                                            }
                                        }]
                                    },
                                    {
                                        "name": "description",
                                        "parts": [{
                                            "text": {
                                                "content": "Freshchat is a cloud based messaging solution that allows you to effectively interact with your business users."
                                            }
                                        }]
                                    },
                                    {
                                        "name": "callback",
                                        "parts": [{
                                            "callback": {
                                                "payload": "Freshchat selected",
                                                "label": "Select"
                                            }
                                        }]
                                    },
                                    {
                                        "name": "view",
                                        "parts": [{
                                            "url_button": {
                                                "url": "https://developers.freshchat.com/api/#introduction",
                                                "label": "View documentation",
                                                "target": "_self"
                                            }
                                        }]
                                    }]
                                }
                            }]
                        }
                    ]
                }
            }
        ],
        "channel_id": "b0247bdb-2796-4489-bd0a-09c22b5440dc",
        "actor_type": "agent",
        "actor_id": "1de5d130-1c62-48cf-8349-1b39c60d0c28"
    }
]
EXPAND ↓

The response enabler rendered is as follows:
     

Example 5 - Template message with a drop-down list

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
"messages": [
    {
        "message_parts": [{
            "text": {
                "content": "How many employees do you have?"
            }
        }],
        "reply_parts": [{
            "template_content": {
                "type": "quick_reply_dropdown",
                "sections": [{
                    "name": "options",
                    "parts": [{
                        "quick_reply_button": {
                            "label": "0-50",
                            "custom_reply_text": "Zero to Fifty",
                            "payload": "Zero to Fifty payload"
                        }
                    },
                    {
                        "quick_reply_button": {
                            "label": "50-100",
                            "custom_reply_text": "Fifty to hundred",
                            "payload": "Fifty to hundred"
                        }
                    },
                    {
                        "quick_reply_button": {
                            "label": "500+"
                        }
                    }]
                }]
            }
        }],
        "channel_id": "b0247bdb-2796-4489-bd0a-09c22b5440dc",
        "actor_type": "agent",
        "actor_id": "1de5d130-1c62-48cf-8349-1b39c60d0c28"
    }
]
EXPAND ↓

The response enabler rendered is as follows:
     

Create a conversation

Creates a conversation object based on the information specified in the request body. The request body parameter should be a valid JSON object of the specified format.

post
/v2/conversations
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
curl -X POST "https://<Freshchat_account_URL>.com/v2/conversations/" 
  -H "accept: application/json"
  -H "content-type: application/JSON" 
  -H "Authorization: Bearer eyJraxxx24X0"
  
    -d "{
      'status': 'new',
      'messages': [
          {
            'message_parts': [{
              'text': {
                'content': 'Hii! Need help in receiving the refund.'
                }
             }],
             'channel_id': '71df7c11-df1e-4365-80e3-75a434c9caf0',
             'message_type': 'normal',
             'actor_type': 'user',
             'actor_id':'86a76727-f5f7-40b5-8f93-309043646b1c20230415141608'
          }
      ],
      'channel_id': '71df7c11-df1e-4365-80e3-75a434c9caf0',
      'assigned_org_agent_id': '462153445185974756',
      'assigned_agent_id': '1ad50c45-050b-4702-9300-478ddcf23c65',
      'assigned_group_id': 'e769cd13-0cd3-4d64-81ac-32657642a24d',
      'properties': {
        'priority': 'Low',
        'cf_type': 'General Query',
        'cf_rating': '3',
        'cf_supported_products': ['Freshchat', 'Freshdesk']
      },
      'users': [{ 
        'id': '86a76727-f5f7-40b5-8f93-309043646b1c20230415141608'
      }]

    }"
EXPAND ↓
Note: For information on how to retrieve the Freshchat account URL that is to be used in the API request, see Retrieve the account URL.
The request body parameter
Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "status": "new",
    "messages": [
      {
        "message_parts": [{
        "text": {
          "content": "Hii! Need help in receiving the refund."
          }
        }],

        "channel_id": "71df7c11-df1e-4365-80e3-75a434c9caf0",
        "message_type": "normal",
        "actor_type": "user",
        "actor_id":"86a76727-f5f7-40b5-8f93-309043646b1c20230415141608"
      }
    ],
    "channel_id": "71df7c11-df1e-4365-80e3-75a434c9caf0",
    "assigned_org_agent_id": "462153445185974756",
    "assigned_agent_id": "1ad50c45-050b-4702-9300-478ddcf23c65",
    "assigned_group_id": "e769cd13-0cd3-4d64-81ac-32657642a24d",
    "properties": {
      "priority": "Low",
      "cf_type": "General Query",
      "cf_rating": "3",
      "cf_supported_products": ["Freshchat", "Freshdesk"]
    },
    "users": [{ 
      "id": "86a76727-f5f7-40b5-8f93-309043646b1c20230415141608"
    }]
  }
EXPAND ↓
Attributes
Attribute Name Data Type Description
status string Status of the conversation.
Possible values: new, assigned, resolved, reopened
channel_idMandatory string Identifier of the topic under which the conversation is to be created.
assigned_agent_id string Identifier of the agent to whom the conversation is assigned for resolution.
assigned_org_agent_id string Organization-level identifier of the agent to whom the conversation is assigned for resolution.
assigned_group_id string Identifier of the group to which the conversation is assigned for resolution.
assigned_org_group_id string Organization-level identifier of the group to which the conversation is assigned for resolution.
messagesMandatory array of message objects Details of the messages that constitute the conversation.
properties VALID ATTRIBUTE ONLY FOR CHAT ACCOUNTS AVAILABLE AS PART OF THE FRESHSALES SUITE object Details of the conversation properties configured for the Freshchat account.
The attribute contains the names of the conversation properties configured and the corresponding values populated, as a valid JSON object of key - value pairs.
Note: You can set the default conversation property - priority - through this API. The custom conversation properties are specified by the prefix cf_ to their names. To set other conversation properties such as agent and group, use the assigned_agent_id and assigned_group_id attributes.
users array of objects Details of the user who initiated the conversation.
Attribute of the object:
id (string): Identifier of the user who initiated the conversation, auto-generated when a user record is created in the Freshchat system.
Response

A successful request returns 202 Accepted along with the created conversation object. The object contains the conversation_id. In further API calls, the conversation_id that is returned can be used to update the corresponding conversation information or retrieve information.

Note: For Freshchat accounts available as part of Freshsales Suite, the response object contains the attribute properties.priority. By default, the conversation is created with the value of properties.priority as Low.

Retrieve a conversation

Identifies a conversation by the conversation_id passed in the request and returns the corresponding information as a conversation object.

get
/v2/conversations/{conversation_id}
Path parameters
Parameter Name Data Type Description
conversation_idMandatory string Identifier of the conversation object, auto-generated when a conversation record is created in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<Freshchat_account_URL>/conversations/83dd2824-7090-4a10-877d-863f394c610f" 
	-H "accept: application/json" 
	-H"Authorization: Bearer eyJnxxoc"
EXPAND ↓
Note: For information on how to retrieve the Freshchat account URL that is to be used in the API request, see Retrieve the account URL.
Response

A successful request returns 200 OK along with the retrieved conversation object. The attributes, conversation.messages and conversation.users are not retrieved as part of the response object.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
	"conversation_id": "83dd2824-7090-4a10-877d-863f394c610f",
	"app_id": "1c4dabcf-61d5-4490-b1a5-d3ff62c8e664",
	"status": "assigned",
	"channel_id": "71df7c11-df1e-4365-80e3-75a434c9caf0",
	"assigned_org_agent_id": "566895102921767652",
	"assigned_agent_id": "1ad50c45-050b-4702-9300-478ddcf23c65",
	"skill_id": 0,
	"properties": {
		"priority": "Low",
		"cf_type": "General Query",
		"cf_rating": "3",
		"cf_supported_products": ["Freshchat", "Freshdesk"]
	}
}
EXPAND ↓

Update a conversation

Identifies a conversation by the conversation_id passed in the request and updates the object with the information specified in the request body. The request body parameter should be a valid JSON object of the specified format. Through this API you can:

  • Resolve an open conversation
  • Reopen a resolved conversation
  • Assign or reassign a conversation to an agent and/or group
  • Unassign a conversation
  • Modify the priority of a conversation
  • Modify the values of the custom properties of a conversation

put
/v2/conversations/{conversation_id}
Path parameters
Parameter Name Data Type Description
conversation_idMandatory string Identifier of the conversation object, auto-generated when a conversation record is created in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl -X PUT "https://<Freshchat_account_URL>/conversations/83dd2824-7090-4a10-877d-863f394c610f" 
	-H "accept: application/json" 
	-H "Authorization: Bearer eyJnxxxoc" 
	-H "content-type: application/JSON" 
	-d "{ 
  	'status': 'resolved',
		'channel_id': '71df7c11-df1e-4365-80e3-75a434c9caf0',
		'assigned_org_agent_id': '566895102921767652',
		'assigned_agent_id': '1ad50c45-050b-4702-9300-478ddcf23c65',
		'assigned_org_group_id': 'c2937604-0a08-43c2-a09c-e77f5f55678d',
		'assigned_group_id': 'bfdc3b66-6de3-4124-b8b7-c37059087d88',
		'properties': {
			'cf_type': 'Technical Query',
			'cf_rating': '5',
			'cf_supported_products': ['Freshchat', 'Freshsales Suite']
		}
	}"
EXPAND ↓
Note: For information on how to retrieve the Freshchat account URL that is to be used in the API request, see Retrieve the account URL.
The request body parameter
Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
{ 
	"status": "resolved",
	"channel_id": "71df7c11-df1e-4365-80e3-75a434c9caf0",
	"assigned_org_agent_id": "566895102921767652",
	"assigned_agent_id": "1ad50c45-050b-4702-9300-478ddcf23c65",
	"assigned_org_group_id": "c2937604-0a08-43c2-a09c-e77f5f55678d",
	"assigned_group_id": "bfdc3b66-6de3-4124-b8b7-c37059087d88",
	"properties": {
		"cf_type": "Technical Query",
		"cf_rating": "5",
		"cf_supported_products": ["Freshchat", "Freshsales Suite"]
	}
}
EXPAND ↓
Attributes

Note: Only the values of the status, assigned_agent_id, assigned_group_id, and properties attributes can be updated using this API.

Attribute Name Data Type Description
status string Status of the conversation.
Possible values: new, assigned, resolved, reopened
channel_id string Identifier of the topic under which the conversation is created, auto-generated when a topic is created in the Freshchat system.
assigned_org_agent_id string Organization-level identifier of the agent, to whom the conversation is assigned for resolution.
assigned_agent_idMandatory attribute in the request body parameter if the value of conversation.status is assigned. string Identifier of the agent assigned to the conversation, auto-generated when an agent’s information is configured in the Freshchat system.
Note: Ensure that the agent to whom the conversation is assigned belongs to the group to which the conversation is assigned.
assigned_org_group_id string Organization-level identifier of the group, to which the conversation is assigned for resolution.
assigned_group_id string Identifier of the group to which the conversation is assigned, auto-generated when a group is created in the Freshchat system.
properties VALID ATTRIBUTE ONLY FOR CHAT ACCOUNTS AVAILABLE AS PART OF THE FRESHSALES SUITE object Details of the conversation properties configured for the Freshchat account.
The attribute contains the names of the conversation properties configured and the corresponding values populated, as a valid JSON object of key - value pairs.
Note: You can update the default conversation property - priority - through this API. The custom conversation properties are specified by the prefix cf_ to their names. To update other conversation properties such as agent and group, use the assigned_agent_id and assigned_group_id attributes.

To resolve a conversation, in the request body, specify the status attribute value as resolved.

To reopen a conversation, in the request body, specify the status attribute value as reopened. If there is an agent assigned to the conversation, the agent is unassigned; the status of the conversation changes to new. While reopening the conversation, you can also reassign the conversation to a new group.

To assign a conversation to a group, in the request body, specify the status attribute value as assigned and the assigned_group_id attribute value as the group id of the group to which the conversation is assigned. The conversation gets assigned to the specified group and the conversation status changes to new.

To assign a conversation to an agent, in the request body, specify the status attribute value as assigned and the assigned_agent_id attribute value as the agent id of the agent to whom the conversation is assigned. If the conversation is assigned to a group, ensure that the agent belongs to the group to which the conversation is assigned. You can assign the conversation to an agent without assigning the conversation to a group.

To unassign a conversation from the assigned agent or group, in the request body, specify an empty value (" ") for the assigned_agent_id or assigned_group_id attribute.

Response

A successful request returns 200 OK along with the updated conversation object.

List messages in a conversation

Identifies a conversation by the conversation_id passed in the request and returns a list of the messages that constitute the conversation.

get
/v2/conversations/{conversation_id}/messages
Query parameters

You can use the following query parameters to limit the response data. Ensure that the query parameter values are URL encoded.

Parameter Name Description Example
from_time

Should be a date-time value specified in the UTC format.		 Limits the response to message objects whose created_time value is a time after the parameter value or matches the parameter value.

GET /conversations/e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd/messages?from_time=2022-12-01T10:00:00.000Z
page The page number starting from which the response data is to be retrieved.
Default value: 1

GET /conversations/e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd/messages?page=1
items_per_page Number of message objects to be displayed in each page in the response.
Note: A maximum of 50 message objects can be displayed in each page.
Default value: 20

GET /conversations/e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd/messages?page=1&items_per_page=50
Path parameters
Parameter Name Data Type Description
conversation_idMandatory string Identifier of the conversation object, auto-generated when a conversation record is created in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/conversations/e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd/messages?from_time=2022-11-29T10:00:00.000Z&page=1" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJraxxxnoc"
EXPAND ↓
Response

A successful request returns 200 OK along with the messages that constitute the conversation, as an array. Each array entry is a message object with the corresponding attributes. The response data is limited by the query parameters passed in the request.

In the response, for a message, the reply_parts attribute is present only for agent-sent or bot-sent messages. This attribute is used to construct a response enabler that enables users to respond quickly and with specific inputs. Through the response enabler, if a user sends a response to the conversation, the response is available in the conversation as a user-sent message and response content is available as text, image, or file in the messages_parts attribute.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
{
    "messages": [
        {
            "message_parts": [
                {
                    "text": {
                    "content": "Test message"
                    }
                }
            ],
            "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7",
            "actor_id": "1de5d130-1c62-48cf-8349-1b39c60d0c28",
            "org_actor_id": "462153445185974756",
            "id": "8c19d985-5b81-4f8c-a1c1-5c61a67682a0",
            "channel_id": "214d3647-6f90-4b67-a97b-221f7f6fc7c9",
            "conversation_id": "e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd",
            "interaction_id": "678911017474140-1669703919894",
            "message_type": "normal",
            "actor_type": "agent",
            "created_time": "2022-12-01T09:49:55.062Z",
            "user_id": "186a0a5c-7d30-4cb3-9a55-9d6534cbbf26",
            "restrictResponse": false,
            "botsPrivateNote": false
        },
        {
            "message_parts": [
                {
                    "text": {
                        "content": "Message sent along with a file attachment."
                    }
                },
                {
                    "file": {
                        "name": "Availability.xlsx",
                        "url":"https://fc.s3.aws.com/f51/f_files/file_Availability.xlsx?response-content-disposition=Availability.xlsx&response-content-type=application&X-Amz-Security-Token=Ixx99",
                        "file_size_in_bytes": 15147,
                        "content_type":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
                    }
                }
            ],
            "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7",
            "actor_id": "1de5d130-1c62-48cf-8349-1b39c60d0c28",
            "org_actor_id": "462153445185974756",
            "id": "6b498753-e825-4bc9-9a5f-b1d5ca5acce9",
            "channel_id": "214d3647-6f90-4b67-a97b-221f7f6fc7c9",
            "conversation_id": "e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd",
            "interaction_id": "678911017474140-1669703919894",
            "message_type": "normal",
            "actor_type": "agent",
            "created_time": "2022-11-30T11:59:38.060Z",
            "user_id": "186a0a5c-7d30-4cb3-9a55-9d6534cbbf26",
            "restrictResponse": false,
            "botsPrivateNote": false
        },
        {
            "message_parts": [
                {
                    "text": {
                        "content": "Message can be triggered to show a value in the dialogue. Render the responses as multiple button options, as shown below."
                    }
                }
            ],
            "reply_parts": [
                {
                    "collection": {
                        "sub_parts": [
                            {
                                "quick_reply_button": {
                                    "label": "Value 1"
                                }
                            },
                            {
                                "quick_reply_button": {
                                    "label": "Value 2"
                                }
                            },
                            {
                                "quick_reply_button": {
                                    "label": "Value 3"
                                }
                            },
                            {
                                "help_text": {
                                    "v1_help_text_fragment": {
                                        "fragment_type": 8,
                                        "content_type": "text/html",
                                        "content": "Please type the option number e.g. 1 to select the first option",
                                        "position": 0
                                    },
                                    "content": "Please type the option number e.g. 1 to select the first option"
                                }
                            }
                        ]
                    }
                }
            ],
            "app_id": "c69641e9-8a85-4da1-858e-77169b0c76a7",
            "id": "e0725ab4-30f0-4c18-9189-43bdb1949a20",
            "conversation_id": "e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd",
            "interaction_id": "678911017474140-1669703919894",
            "created_time": "2022-11-29T11:48:37.329Z",
            "user_id": "186a0a5c-7d30-4cb3-9a55-9d6534cbbf26",
            "restrictResponse": false,
            "botsPrivateNote": false
          }
        ],
        "link": {
            "rel": "self",
            "href": "/v2/conversations/e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd/messages?1=1&page=2&items_per_page=50&from_time=2022-11-29T06:36:55.799Z"
        }
      }
EXPAND ↓

Send a message to a conversation

Identifies a conversation by the conversation_id passed in the request and sends a message to the conversation.

post
/v2/conversations/{conversation_id}/messages
Path parameters
Parameter Name Data Type Description
conversation_idMandatory string Identifier of the conversation object, auto-generated when a conversation record is created in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
curl -X POST "https://<account>.freshchat.com/v2/conversations/e083b4c7-fc1e-4fa1-b9c4-e1497db5eabd/messages" 
    -H "accept: application/json" 
    -H "ASSUME-IDENTITY: false" 
    -H "Content-Type: application/json" 
    -H "Authorization: Bearer eyJraxxxnoc" 
    -d " {
            'message_parts': [
                {
                'text': {
                    'content': 'Do you Agree??'
                }
                }
            ],
            'reply_parts': [
                {
                'collection': {
                    'sub_parts': [
                    {
                        'quick_reply_button': {
                            'label': 'Yes'
                        }
                    },
                    {
                        'quick_reply_button': {
                            'label': 'No'
                        }
                    }
                    ]
                }
                }
            ],
            'message_type': 'normal',
            'actor_type': 'agent',
            'user_id': '186a0a5c-7d30-4cb3-9a55-9d6534cbbf26',
            'actor_id': '1de5d130-1c62-48cf-8349-1b39c60d0c28'
     }"
EXPAND ↓
Response

A successful request returns 200 OK along with the created message object.

List all conversation properties

Retrieves a list of all conversation properties configured in the Freshchat system.

Important: This API is available only for chat accounts available as part of Freshsales Suite.

get
/conversations/fields
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<Freshchat_account_URL>/conversations/fields" 
	-H "accept: application/json" 
	-H"Authorization: Bearer eyJxxxDM"
EXPAND ↓
Note: For information on how to retrieve the Freshchat account URL that is to be used in the API request, see Retrieve the account URL.
Response

A successful request returns 200 OK along with the details of all the conversation properties’ fields configured for the account, as an array. Each array entry is a conversation property field object with the corresponding attributes.

Note: In the Freshchat UI > Conversation properties widget, agent, group, status, and priority are available as default properties. When all the conversation properties configured in the Freshchat system are retrieved through the List all conversation properties API, the default conversation properties group, agent, and status are not retrieved as part of the response object. Only priority is retrieved as part of the response object along with the custom properties. You can use the Retrieve a conversation API to view the agent (assigned_agent_id), group (assigned_group_id), and status associated with the conversation.
Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
[
	{
		"id": "675fb5f6-ff96-4f73-a9b3-e62554958c65",
		"name": "priority",
		"label": "Priority",
		"type": "DROPDOWN",
		"custom": false,
		"editable": true,
		"position": 174,
		"required": false,
		"choices": [
			{
				"id": "1",
				"value": "Low"
			},
			{
				"id": "2",
				"value": "Medium"
			},
			{
				"id": "3",
				"value": "High"
			},
			{
				"id": "4",
				"value": "Urgent"
			}
		],
		"default_value": "1"
	},
	{
		"id": "98b26df9-168f-4f1c-8dcb-9abef7ee99f2",
		"name": "cf_type",
		"label": "Type",
		"type": "DROPDOWN",
		"custom": true,
		"editable": true,
		"position": 175,
		"required": false,
		"choices": [
			{
				"id": "62c868a6-66e5-4c3e-863e-ddaa53f1e50b",
				"value": "General Query"
			},
			{
				"id": "9212cbf7-ac45-4383-aab6-99b902fd9071",
				"value": "Technical Query"
			},
			{
				"id": "fab25bc8-2135-43e7-950d-1a98ac377e61",
				"value": "Feature Request"
			},
			{
				"id": "1b6d82c8-8c0c-4278-ad18-ea0ce635a043",
				"value": "Feedback"
			}
		]
	},
	{
		"id": "4d2e24e6-6742-421b-bb5a-f880ecb053c2",
		"name": "cf_rating",
		"label": "Rating",
		"type": "NUMBER",
		"custom": true,
		"editable": true,
		"position": 126,
		"required": false,
		"choices": []
	}
]
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the conversation property field object, auto-generated when a conversation property field is configured for a Freshchat account.
label string Name of the conversation property that is displayed to the user.
name string Name of the field which is used internally.
type string Field type.
Possible values: TEXT, DROPDOWN, CHECKBOX, PARAGRAPH, NUMBER, DECIMAL, DATE, MULTI_SELECT_DROPDOWN
custom boolean Specifies whether the conversation property is a custom property configured in the Freshchat account.
Possible values: true, false
editable boolean Specifies whether the field value can be modified.
Possible values: true, false
position integer Position of the conversation property field in the Conversation property widget.
required boolean Specifies whether it is mandatory for the field to have a valid value to resolve a conversation.
Possible values: true, false
choices array of objects Details of the choices specified for a field of type DROPDOWN or MULTI_SELECT_DROPDOWN.
Attributes of the object:
id (integer): Identifier of the choice, auto-generated when a new choice is added to the drop-down or multiselect drop-down field.
value (string): Name of the choice as displayed to the agent.
Note: The attribute will have a valid value only when the value of the type is DROPDOWN or MULTI_SELECT_DROPDOWN. For other types, the value is an empty array.
default_value string Default value of the field.
Note: The attribute is present only for a priority field. By default, all conversations are given low priority and the default_value is 1.

Files

Freshchat permits agents to attach files to a conversation from their computer or upload files to the file repository. This API enables uploading a file to an S3 bucket linked to the Freshchat account. By default, Freshchat allows PDFs, images, videos, and text files to be uploaded as files.

Endpoints

POST /files/upload

Upload a file

When a file is uploaded as an attachment to a conversation or to the file repository, the Freshchat system uploads it to the S3 bucket, and the file attributes such as an unique file hash value are returned in the response. The response can be used as an input to create a conversation with the file as an attachment.

Notes:
  • Only one file can be uploaded per request.
  • The file size should not exceed 25 MB.
post
v2/files/upload
Sample request | Curl
Copied Copy 
1
2
3
4
5
curl -X POST "https://<account>.freshchat.com/v2/files/upload" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJraWQiOiJjxxxk6xsM" 
        -H "Content-Type: multipart/form-data" 
        - F 'file=@"/Users/Downloads/img.jpg"'
EXPAND ↓
The request body parameter
Example 
1
file=@"/Users/Downloads/img.jpg
EXPAND ↓
Attributes
Attribute Name Data Type Description
file multipart/form-data Location from which the file is retrieved for upload.
Response

A successful request returns 200 OK along with the details of the uploaded file, including the file’s name, size, content type, hash, security status, and extension.

Example 
1
2
3
4
5
6
7
8
{
    "file_name": "box_logo.jpg",
    "file_size": 4952,
    "file_content_type": "image/jpeg",
    "file_extension_type": "jpg",
    "file_hash": "g9dld97mr9",
    "file_security_status": "AV_PENDING"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
file_name string Name of the file uploaded.
file_size integer Size of the file uploaded.
file_content_type string Type of the content in the uploaded file.
file_extension_type string Extension of the file uploaded.
file_hash string Unique identifier of the uploaded file in the internal database, which allows easy identification when creating a conversation with the attached file.
file_security_status string Status of the security can for the uploaded file.
Possible values:
  • AV_PENDING: The uploaded file is in queue for security scan check.
  • AV_FAILURE: File malware check failed.
  • SAFE_FILE: The uploaded file is secure.
  • MALWARE_FILE: The uploaded file has a malware.
  • TOO_LARGE_FOR_MALWARE_CHECK: The uploaded file is too large to add to the security scan queue.

Agents

Freshchat enables organizations to converse with their customers. Agents are the organization’s members who use Freshchat to converse with their customers.
When a conversation is initiated, an agent is manually or automatically assigned based on the assignment rules defined in the Freshchat system.

Endpoints

GET /agents
POST /agents
GET /agents/status
DELETE /agents/{agent_id}
PATCH /agents/{agent_id}
GET /agents/{agent_id}
PUT /agents/{agent_id}

The agent object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
	"id": "1ab37a05-7b3e-42ee-bcbe-283fd093408c",
	"created_time": "2022-10-12T22:56:14.825Z",
	"agent_capacity": 0,
	"agent_status": {
		"name": "Inactive on Intelli Assign"
	},
	"availability_status": "UNAVAILABLE",
	"avatar": {
		"url": "https://web.freshchat.com/img/johndoe.png"
	},
	"biography": "Hi!!I am your Technical Support Engineer",
	"email": "alice.adrian@email.com",
	"first_name": "Alice",
	"freshid_group_ids": [],
	"freshid_uuid": "",
	"groups": [
		"a9a02944-cadd-454f-91a4-2165f37a2737"
	],
	"is_deactivated": false,
	"is_deleted": false,
	"last_name": "Adrian",
	"license_type": "fulltime",
	"locale": "en-us",
	"login_status": false,
	"org_contact_id": "",
	"role_id": "AGENT",
	"role_name": "Agent",
	"routing_type": "INTELLIASSIGN",
	"skill_id": "44bb89c8-0aa3-4f83-a07c-d75e909f253d",
	"social_profiles": [{
		"type": "facebook",
		"id": "alice.adrian"
	}],
	"timezone": "Asia/Kolkata"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
created_time string Timestamp of when the agent’s record was created in the Freshchat system, specified in the UTC format.
agent_capacity integer Number of active conversations that the agent can handle when the agent is active on IntelliAssign.
agent_status object Omniroute, Intelliassign, or Custom status of the agent.
A business can add new custom statuses, such as Away, In a meeting, and so on, if the custom activity state feature is enabled for a business account that uses Freshchat.
Attributes of the object:
id (string): Identifier of custom status, auto-generated when a new status is added to the Freshchat system.
name (string): Status message.
availability_status string Status of the agent’s availability for conversation auto-assignment.
Possible values: AVAILABLE, UNAVAILABLE
Default value: AVAILABLE
avatar object Image used as the display picture in the agent’s profile.
Attributes of the object:
url (string): Link from which the image is fetched.
biography string Meaningful description about the agent.
email string Email address of the agent.
first_name string First name of the agent.
freshid_group_ids array of strings Identifiers (in the Freshworks’ master record) of the groups to which the agent belongs, specified as an array.
freshid_uuid string Universally unique identifier of the agent across Freshworks’ master record.
groups array of strings Identifiers (in the Freshchat system) of the groups to which the agent belongs, specified as an array.
is_deactivated boolean Specifies whether the agent is deactivated in the Freshchat system.
Possible values: true, false
is_deleted boolean Specifies whether the agent’s details are deleted from the Freshchat system.
Possible values: true, false
last_name string Last name of the agent.
license_type string Employment terms that apply to the agent. For example, Fulltime, Occasional, and so on.
locale string Language associated with the agent’s location, specified in the ISO-639 code.
login_status boolean Specifies whether the agent is logged into the Freshchat system.
Possible values: true, false
org_contact_id string Auto-generated identifier of the Freshchat agent, created when the agent is saved as a contact in the Freshworks’ system.
phone string Phone number of the agent.
role_id string System-generated identifier of the role assigned to the agent, that specifies the level of access permissions the agent has in the Freshchat system.
role_name string Meaningful identifier of the agent’s role that specifies the agent’s level of access in the Freshchat system.
The default roles are Account admin, Admin, Super user, and Agent. An account admin can define custom roles in the Freshchat system.
routing_type string Assignment rule to which the agent is associated.
Incoming conversations can be auto-assigned to agents either through custom defined assignment rules or through (load-based, bandwidth-based) IntelliAssign/Omniroute rules.
Possible values:
  • Intelliassign: Agent is associated with an IntelliAssign rule.
  • OCR: Agent is associated with an Omniroute rule.
DISABLED: Agent is not associated with IntelliAssign/Omniroute rules or is associated with a custom assignment rule.
scope string Level of access that the agent has to the conversations created in the Freshchat system. scope values depend on the role associated with the agent.
Possible values:
Global: Agent can use specific features on all conversations in the Freshchat system.
Group: Agent can use specific features on all conversations assigned to the group to which the agent belongs.
Me: Agent can use specific features only on conversations assigned to the agent.
None: Agent has not been assigned any role.
skill_id string Identifier of the load level mapped to the agent. Load levels define the number of active conversations that an agent can handle, when incoming conversations are assigned to the agent, through IntelliAssign.
When a new load level is created in the Freshchat system, a skill_id value is auto-generated and assigned to the load level.
social_profiles array of objects Details of the agent’s social media profiles, specified as an array of objects.
Attributes of the object:
id (string): User handle of the agent’s social profile.
type (string): Name of the social media platform.
Possible values: facebook, twitter, skype, linkedin
timezone string Timezone to which the agent belongs, in the Area/Location format. For example, Asia/Kolkata, America/Toronto, US/Michigan, and so on.

List all agents

Retrieves a list of all the agents configured in the Freshchat system.

get
/v2/agents
Query parameters

You can use a combination of the following query parameters and pagination parameters to limit or filter the bulk response data. Ensure that the query parameter values are URL encoded.

Parameter Name Description Example
is_deactivated Limits the response to agent objects whose is_deactivated value matches the parameter value.
Valid values: true, false

GET /agents?is_deactivated=true
groups Limits the response to agent objects where at least one of the groups value matches the string specified as the parameter value.

GET /agents?groups=38dd7cdc-d022-4489-8cb5-4fdc35f0b5a7
availability_status Limits the response to agent objects whose availability_status value matches the parameter value.
Valid values: AVAILABLE, UNAVAILABLE

GET /agents?availability_status=UNAVAILABLE
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/agents?page=1&items_per_page=2&sort_order=asc" 
    -H "accept: application/json" 
    -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 200 OK along with all agents’ details, as an array. Each array entry is an agent object with the corresponding attributes. The response data is limited by the query and pagination parameters passed in the request. The response also contains response parameters pertaining to pagination.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{    "agents": [
    {
        "groups": [],
        "role_id": "ACCOUNT_ADMIN",
        "role_name": "Account Admin",
        "is_deactivated": true,
        "is_deleted": false,
        "locale": "en-us",
        "timezone": "Asia/Kolkata",
        "availability_status": "UNAVAILABLE",
        "agent_status": {
            "name": "Inactive on OCR"
        },
        "routing_type": "INTELLIASSIGN",
        "agent_capacity": 2,
        "created_time": "2019-08-14T09:08:11.215Z",
        "id": "a6cc8807-0bc5-49d9-88fc-d9e06ace8c09",
        "first_name": "John",
        "last_name": "Doe",
        "email": "newagent.helouser@yopamil.com",
        "avatar": {},
        "social_profiles": [],
        "login_status": false
    },
    {
        "biography": "This is supposed to be bio for agent.",
        "groups": [],
        "role_id": "ACCOUNT_ADMIN",
        "role_name": "Account Admin",
        "is_deactivated": true,
        "is_deleted": false,
        "locale": "en-us",
        "availability_status": "UNAVAILABLE",
        "agent_status": {
            "name": "Inactive on Intelli Assign"
        },
        "routing_type": "INTELLIASSIGN",
        "agent_capacity": 2,
        "created_time": "2019-04-11T13:38:16.485Z",
        "id": "d37b9c8f-ec59-4c72-9b1d-c06edcb36de1",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "aaa.aaa@yopmail.com",
        "avatar": {},
        "social_profiles": [
            {
                "type": "twitter",
                "id": "tweetme"
            }
        ],
        "login_status": false
    }],
    "pagination": {
        "total_items": 632,
        "total_pages": 316,
        "current_page": 1,
        "items_per_page": 2
    },
    "links": {
        "next_page": {
        "href": "/v2/agents?sort_by=email&items_per_page=2&sort_order=asc&page=2",
        "rel": "agent",
        "type": "GET"
        },
        "first_page": {
        "href": "/v2/agents?sort_by=email&items_per_page=2&sort_order=asc&page=1",
        "rel": "agent",
        "type": "GET"
        },
        "last_page": {
        "href": "/v2/agents?sort_by=email&items_per_page=2&sort_order=asc&page=316",
        "rel": "agent",
        "type": "GET"
        }
    }
}
EXPAND ↓

Create an agent

Creates an agent object based on the information specified in the request body. The request body parameter should be a valid JSON object of the specified format.

post
/v2/agents
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
curl -X POST 
        "https://<account>.freshchat.com/v2/agents"
        -H "accept: application/JSON"
        -H "authorization: Bearer eyJraWQiOiJjxxxdz2Dkl-I" 
        -H "content-type: application/JSON"
        -d "{
            'email': 'alice.adrian@email.com',
            'avatar': {
                'url': 'https://web.freshchat.com/img/johndoe.png'
            },
            'phone': '123456789',
            'biography': 'Hi, I am your Technical Support Engineer.',
            'role_id': 'AGENT',
            'role_name': 'Agent',
            'skill_id': '44bb89c8-0aa3-4f83-a07c-d75e909f253d ',
            'locale': 'en-us',
            'timezone': 'Asia/Kolkata',
            'first_name': 'Alice',
            'last_name': 'Adian',
            'social_profiles': [
                {
                    'id': alice.adrian',
                    'type': 'facebook'
                }
            ],
            'groups': [
                'a9a02944-cadd-454f-91a4-2165f37a2737'
            ]
        }"
EXPAND ↓
The request body parameter
Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
        "avatar": {
            "url": "https://web.freshchat.com/img/johndoe.png"
        },
        "biography": "Hi, I am your Technical Support Engineer.",
        "email": "alice.adrian@email.com",
        "first_name": "Alice",
        "groups": [
            "a9a02944-cadd-454f-91a4-2165f37a2737"
        ],
        "last_name": "Adian",
        "license_type": "FULLTIME"
        "locale": "en-us",
        "org_contact_id": "138763287863827323",
        "phone": "123456789",
        "role_id": "AGENT",
        "role_name": "Agent",
        "skill_id": "44bb89c8-0aa3-4f83-a07c-d75e909f253d", 
        "social_profiles": [
            {
                "type": "facebook",
                "id": "alice.adrian"
            }
        ], 
        "timezone": "Asia/Kolkata"
      }
EXPAND ↓
Attributes
Attribute Name Data Type Description
avatar object Details of the image used as the avatar for the agent profile.
Attributes of the object:
url (string): Link from which the image is fetched.
biography string Meaningful description about the agent.
emailMandatory string Email address of the agent.
first_name string First name of the agent.
groups array of strings Identifiers of the groups to which the agent belongs, specified as an array.
last_name string Last name of the agent.
locale string Language associated with the agent’s location, specified in the ISO-639 code.
phone string Phone number of the agent.
role_id string System-generated identifier of the role assigned to the agent.
role_name string Meaningful identifier of the agent’s role in the Freshchat system.
skill_id string Identifiers of the skill or load mapped to the agent.
social_profiles array of objects Details of the agent’s social media profiles, specified as an array.
Attributes of the object:
id (string): User handle of the agent’s social profile.
type (string): Name of the social media platform.
Possible values: facebook, twitter, skype, linkedin
timezone string Timezone to which the agent belongs, in the Area/Location format. For example, Asia/Kolkata, America/Toronto, US/Michigan, and so on.
Response

A successful request returns 201 Created along with the created agent object. The object contains the id, created_at, and updated_at attributes. In further API calls, the id that is returned can be used to update the corresponding agent information or retrieve information.

Retrieve agent information

Identifies an agent by the agent_id passed in the request and returns the corresponding information as an agent object.

get
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/agents/1ab37a05-7b3e-42ee-bcbe-283fd093408c" 
	-H "accept: application/json" 
	-H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 200 OK along with the retrieved agent object.

Update agent information

Identifies an agent object by the agent_id passed in the request and updates the object with the information specified in the request body. The request body parameter should be a valid JSON object of the specified format. If an attribute value is null or not passed as part of the request payload, the attribute’s existing value is retained.

put
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
curl -X PUT 
    "https://<account>.freshchat.com/v2/agents/1ab37a05-7b3e-42ee-bcbe-283fd093408c"
    -H "accept: application/JSON"  
    -H "authorization: Bearer eyJraWQiOiJjxxskdz2Dkl-I"
    -H "content-type: application/JSON"  
    -d "{
        'email': 'alice.adrian@email.com',
        'avatar': {
            'url': 'https://web.freshchat.com/img/johndoe.png'
        },
        'phone': '123456789',
        'biography': 'Hi!!I am your Technical Support Engineer',
        'role_id': 'AGENT',
        'role_name': 'Agent',
        'skill_id': '44bb89c8-0aa3-4f83-a07c-d75e909f253d ',
        'locale': 'en-us',
        'timezone': 'Asia/Kolkata',
        'first_name': 'Alice',
        'last_name': 'Adrian',
        'social_profiles': [
            {
                'type': 'facebook',
                'id': 'alice.adrian'
            }
        ],
        'groups': [
            'a9a02944-cadd-454f-91a4-2165f37a2737'
        ],
        'license_type': 'FULLTIME'
    }"
EXPAND ↓
Response

A successful request returns 200 OK along with the updated agent object.

List all agent statuses

Retrieves a list of all custom statuses configured in the Freshchat system. A business can add new custom statuses, such as Away, In a meeting, and so on, if the custom activity state feature is enabled for a business account that uses Freshchat.

get
v2/agents/status
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/agents/status" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 200 OK along with all agents’ status, as an array. Each array entry is an agent status object with the corresponding attributes.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
        "states": [
          {
            "id": "b75c38ce-7471-4db9-900f-238cd1b51938",
            "name": "BRB"
          },
          {
            "id": "0c5a8e92-a6ad-4a7b-918f-5279760d2c4f",
            "name": "lol"
          },
          {
            "id": "3f2c438e-cb78-45dc-a395-fa53363119f3",
            "name": "online test"
          },
          {
            "id": "f5f09dc1-f09d-45f5-b776-e577874a08ac",
            "name": "testStatus"
          },
          {
            "id": "fa8230ff-cfbc-4e62-8ecc-419d38ffb068",
            "name": "Testing "
          },
          {
            "id": "ca6cfff6-73c9-4b0d-808f-d195990f136f",
            "name": "test"
          },
          {
            "id": "edca4f45-6fda-4613-a17c-7c118931c4bc",
            "name": "Happy vacations"
          },
          {
            "id": "0062b314-5b7d-466f-963e-1e0a723d4d64",
            "name": "In a meeting"
          },
          {
            "id": "822965c6-4069-4d37-ab20-9086fca35d58",
            "name": "sleep"
          },
          {
            "id": "f3e21aee-b5b0-417e-a113-796e865ad273",
            "name": "Unstoppable"
          },
          {
            "id": "4e669421-ff3a-461e-8a34-e28f73d6e817",
            "name": "Vacation"
          }
        ]
      }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the status object, auto-generated when a new custom status is configured in the Freshchat system.
name string Status message.

Update agent status

Identifies an agent by the agent_id passed in the request and updates the status of the agent with the status specified in the request body.

Notes:
1. To view the list of status values that can be used to update an agent’s current status, use the List all agent statuses API.
2. You can use this API only to update an agent’s existing status (IntelliAssign/OCR/Custom status) to a custom status. You cannot use this API to update a custom status to IntelliAssign/OCR states (Active/Inactive).

patch
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
curl -X PATCH 
        https://<account>.freshchat.com/v2/agents/1de5d130-1c62-48cf-8349-1b39c60d0c28 
        -H "accept: application/JSON"
        -H "authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
        -H "content-type: application/JSON"
        -d "{
        "agent_status":
            {
            "id": "0062b314-5b7d-466f-963e-1e0a723d4d64",
            "name": "In a meeting"
            }
        }"
EXPAND ↓
The request body parameter
Example 
1
2
3
4
5
"agent_status":
        {
        "id": "0062b314-5b7d-466f-963e-1e0a723d4d64",
        "name": "In a meeting"
        }
EXPAND ↓
Attributes
Attribute Name Data Type Description
agent_status object Value that has to be updated as the current agent status.
Attributes of the object:
id (string): Identifier of custom status, auto-generated when a new status is added to the Freshchat system. Should be a valid states.id value.
name (string): Status message. Should be a valid states.name value.
Note: If no value is specified for agent_status the previous status is retained.
Response

A successful request returns 200 OK along with the following response; availability_status specifies the agent’s availability for conversation auto-assignment, based on the updated status.

Example 
1
2
3
4
5
6
7
{
    "availability_status": "UNAVAILABLE",
    "agent_status": {
        "id": "0062b314-5b7d-466f-963e-1e0a723d4d64",
        "name": "In a meeting"
    }
}
EXPAND ↓

Delete an agent

Identifies an agent by the agent_id passed in the request and permanently deletes the agent’s record from the Freshchat system. The agent details cannot be retrieved from the Freshchat system after this delete which primarily serves to meet General Data Protection Regulation (GDPR) requirements.

delete
/v2/agents/{agent_id}
Path parameters
Parameter Name Data Type Description
agent_idMandatory string Identifier of the agent object, auto-generated when an agent information is configured in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
curl -X DELETE "https://<account>.freshchat.com/v2/agents/c6c3a1b2-00d8-4d42-8ff7-4abb4c7fc496" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 202 Accepted along with the corresponding response message.

Example 
1
2
3
4
5
{
    "code": 202,
    "status": "ACCEPTED",
    "message": "Agent deletion request accepted"
}
EXPAND ↓

Groups

A business can organize its agents into different groups. Conversations can be assigned to these groups manually or through auto-routing. Any agent in the group can pick a conversation, assign it to self, and resolve the queries in the conversation.

Endpoint

GET /groups

The group object

Example 
1
2
3
4
5
6
7
{
    "id": "b23cd57a-0c28-47a5-8fbf-3807cdcf80c0",
    "name": "Automation",
    "description": "Group that handles automation",
    "routing_type": "OCR",
    "routing_logic": "OCR"	  
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the group, auto-generated when a group is configured in the Freshchat system.
name string Name of the group.
description string Meaningful description about the group.
routing_type string Type of auto-routing associated with the group.
Possible values:
  • INTELLIASSIGN: The auto-routing mechanism that assigns conversations to the group is IntelliAssign. For information on how IntelliAssign works, see What is IntelliAssign in Freshchat?
  • OCR: The auto-routing mechanism that assigns conversations to the group is Omni-channel routing. For information on how Omni-channel routing works, see What is Omni-route?
  • DISABLED: Auto-assignment through IntelliAssign/omniroute is disabled.

Note: If conversations are routed to a group through Assignment rules, routing_type is DISABLED.
routing_logic string Routing logic based on which conversations are auto-assigned.
Possible values:
  • DISABLED: If auto-routing through Intelliassign/Omiroute is disabled for all groups (at account level), routing_logic is DISABLED.

If routing_type is INTELLIASSIGN, the routing_logic can be one of the following:
  • LOAD_BASED
  • ROUND_ROBIN

For information on load based and round robin logic, see Choose IntelliAssign logic.
If routing_type is OCR, the routing_logic is OCR.
Note: For a specific group, if IntelliAssign/Omniroute is disabled, the routing_logic attribute specifies the logic that is set at the account level.

List all groups

Retrieves a list of all the groups configured in the Freshchat system.

get
/v2/groups
Query parameters

You can use a combination of valid query parameters to limit or filter the response data.

Sample request | Curl
Copied Copy 
1
2
3
4
curl -X GET 
  "https://<account>.freshchat.com/v2/groups?page=1&items_per_page=10&sort_order=asc&sort_by=name"  
  -H "accept: application/json" 
  -H "Authorization: Bearer eyJxyzQ"
EXPAND ↓
Response

A successful request returns a 200 OK along with the groups array. Each array element is a group object. The response is curated based on the pagination parameters passed in the request. The response also contains response parameters pertaining to pagination.

Example 1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{  "groups": [
    {
      "id": "d56d224e-1a7c-4520-8134-074143f8d958",
      "name": "Sales",
      "description": "Group to handle Sales related queries",
      "routing_type": "OCR",
      "routing_logic": "OCR"
    },
    {
      "id": "1cb699d5-12c1-4cac-acbd-d95c8f75e497",
      "name": "Support",
      "description": "Group to handle support tickets",
      "routing_type": "DISABLED",
      "routing_logic": "OCR"
    },
    {
      "id": "b23cd57a-0c28-47a5-8fbf-3807cdcf80c0",
      "name": "Automation",
      "description": "Group that handles automation",
      "routing_type": "OCR",
      "routing_logic": "OCR"
    }
  ]
}
EXPAND ↓
Example 2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{"groups": [
    {
      "id": "d56d224e-1a7c-4520-8134-074143f8d958",
      "name": "Sales",
      "description": "Group to handle Sales related queries",
      "routing_type": "DISABLED",
      "routing_logic": "DISABLED"
    },
    {
      "id": "1cb699d5-12c1-4cac-acbd-d95c8f75e497",
      "name": "Support",
      "description": "Group to handle support tickets",
      "routing_type": "DISABLED",
      "routing_logic": "DISABLED"
    },
    {
      "id": "b23cd57a-0c28-47a5-8fbf-3807cdcf80c0",
      "name": "Automation",
      "description": "Group that handles automation",
      "routing_type": "DISABLED",
      "routing_logic": "DISABLED"
    }
  ]
}
EXPAND ↓
Example 3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{"groups": [
    {
      "id": "d56d224e-1a7c-4520-8134-074143f8d958",
      "name": "Sales",
      "description": "Group to handle Sales related queries",
      "routing_type": "INTELLIASSIGN",
      "routing_logic": "ROUND_ROBIN"
    },
    {
      "id": "1cb699d5-12c1-4cac-acbd-d95c8f75e497",
      "name": "Support",
      "description": "Group to handle support tickets",
      "routing_type": "INTELLIASSIGN",
      "routing_logic": "ROUND_ROBIN"
    },
    {
      "id": "b23cd57a-0c28-47a5-8fbf-3807cdcf80c0",
      "name": "Automation",
      "description": "Group that handles automation",
      "routing_type": "DISABLED",
      "routing_logic": "ROUND_ROBIN"
    }
  ]
}
EXPAND ↓

Channels-(topics)

Freshchat enables organizations to create topics (channels) to streamline conversations. A topic can be associated with a group; whenever a message is received under the topic, it is automatically assigned to the group. The Freshchat web messenger displayed on the organization’s web pages can be customized to display the topics created in the Freshchat system.

The channels API retrieves information pertaining to all topics configured in the Freshchat system.

Endpoint

GET /channels

The topic object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
        "id": "d645c4a5-2b8c-4109-af56-4887373522e3",
        "updated_time": "2022-11-23T04:56:13.587Z",
        "name": "Services and promotions",
        "icon": {
            "url":"https://fc-pics-bkt-00.s3.aws.com/ff1/f_marketingpic/u_2f/img_a6.jpeg"
            },
        "enabled": true,
        "tags": [
            "sales"
            ],
        "public": true,
        "welcome_message": {
            "message_parts": [{
                "text": {
                    "content": "Hey!! Reach out for exciting promotions."
                }
            }],
        "message_type": "normal"
        },
        "locale": "en"
    }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the channel object, auto-generated when a topic is created in the Freshchat system.
updated_time string Timestamp of when the topic details are last updated in the Freshchat system, specified in the UTC format.
name string A descriptive identifier of the topic.
icon object Pictorial representation of the topic.
Attributes of the object:
url (string): S3 bucket where the uploaded image is stored.
enabled boolean Specifies whether to display the topic on the Freshchat conversation widget (web messenger) that is deployed on an organization’s (customer’s) website.
Possible values: true, false
public boolean Specifies whether the topic is visible across all the web pages in the organization’s website.
Possible values: true, false
Default value: true
tags array of strings Tags (labels) associated with a private topic that help customize the web messenger displayed on the organization’s webpages.
If the public attribute value is false, it means the topic is a private topic and can be visible or hidden in (the web messenger of) a customer’s webpage.
To customize the visibility of a topic, a topic should be declared as private and tags should be associated with the private topic. These tags are used to customize the web messenger of specific webpages.
welcome_message object Message that sets context about the topic.
Attributes of the object:
  • message_parts (array of objects): Details of the welcome message associated with the topic, specified as an array.
    Attribute of the object:
    text (object): Details of the text content that constitutes the welcome message.
      Attribute of the object:
    • content (string): Content of the welcome message.
  • message_type (string): Type of message.
    Possible values: normal
locale
Response attribute returned only if a retrieve by locale API call is run.		 string If multi-language support is enabled for a Freshchat account, after a topic is created, it can be edited for specific locales. Based on the locale of the browser where the web messenger is deployed, the topic is displayed in that specific locale (if it is supported for the topic).
The locale attribute identifies this language as a ISO-639 code.
Note: If no specific languages are configured for the account, the value of locale in the response will be default.

List all channels

Retrieves a list of all the topics created in the Freshchat system.

get
/v2/channels
Query parameters

You can use a combination of the following query parameter and pagination parameters to limit or filter the bulk response data.

Parameter Name Description Example
locale

Must be specified in the ISO-639 format.		 Limits the response to topics whose locale value matches the parameter value.

GET /channels?locale=ge
Notes:
  • The attribute locale is part of the response only when the locale query parameter is included in the request.
  • When locale is not passed in the request or when the value of the locale (language specified in the ISO-639 format) passed in the request is not configured for the Freshchat acocunt, the response includes only the topics created in the primary language set for the Freshchat account. For example, if English is the primary language configured for the Freshchat account, the response includes only the topics with locale as English.
  • If no specific languages are configured for the account, the value of locale in the response will be default.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/channels?page=1&items_per_page=2&sort_order=asc&sort_by=name&locale=en" 
    -H "accept: application/json" 
    -H "Authorization: Bearer eyJraxxxV4"
EXPAND ↓
Response

A successful request returns 200 OK along with all topics’ details, as an array. Each array entry is a topic object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response also contains response parameters pertaining to pagination.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
    "channels": [
        {
            "id": "9c34831f-00b9-4fd0-8184-33105fd6d514",
            "icon": {},
            "updated_time": "2022-11-23T08:47:10.178Z",
            "enabled": false,
            "public": true,
            "name": "Billing Queries",
            "tags": [],
            "welcome_message": {
                "message_parts": [
                {
                    "text": {
                        "content": "Hello!! Need help?"
                    }
                }
                ],
                "message_type": "normal"
            },
            "locale": "en"
        },
        {
            "id": "d645c4a5-2b8c-4109-af56-4887373522e3",
            "icon": {
                "url": "https://fc-use1-00-pics-bkt-00.s3.amazonaws.com/f5a5e46e0b9f058539df57caf009bf21cb579ca17df69204ecf9cb6d5cf3c4f1/f_marketingpicFull/u_2b76cb0dd53d87b5c1507be19c3b08dcff1fcdfde326d496db05a18de367a42f/img_h4pagd8i77_aceacc2e316969c401bb74b472a8869631786e84b38eb87738dd726f9ccf2dc6.jpeg"
            },
            "updated_time": "2022-11-23T09:02:47.181Z",
            "enabled": true,
            "public": true,
            "name": "Services and promotions",
            "tags": [
                "sales"
            ],
            "welcome_message": {
                "message_parts": [
                {
                    "text": {
                        "content": "Hey!! Reach out for exciting promotions."
                    }
                }
                ],
                "message_type": "normal"
            },
            "locale": "en"
        }
    ]
}
EXPAND ↓

CSAT

An organization, which uses Freshchat, can gather feedback and Customer Satisfaction (CSAT) ratings for specific agent-customer conversations. You can use the Create a CSAT score API to identify a conversation and post the customer’s CSAT score to the conversation.

Endpoint

POST /csat/{conversation_id}

Create a CSAT rating for a conversation

Creates a csat object for a conversation, identified by the conversation_id passed in the request. The CSAT object is created based on the request body parameter. The request body parameter should be a valid JSON object of the specified format.

Note: Using this API, you can post CSAT rating only for resolved conversations.
post
/csat/{conversation_id}
Path parameters
Parameter Name Data Type Description
conversation_idMandatory string Identifier of the conversation object, auto-generated when a conversation record is created in the Freshchat system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
curl -X PUT 
  "https://<account>.freshchat.com/v2/csat/7bc48e9b-e75d-4e67-a96c-384396ef8631"
  -H "accept: application/JSON"  
  -H "authorization: Bearer eyJraWQiOiJjxxskdz2Dkl-I"
  -H "content-type: application/JSON"  
  -d "{
        'issue_resolved': true, 
        'rating':5,
        'additional_feedback': 'Issue was resolved in a very short time',
        'reopen_conversation': false
      }"
EXPAND ↓
The request body parameter
Example 
1
2
3
4
5
6
{
    "issue_resolved": true, 
    "rating":5,
    "additional_feedback": "Issue was resolved in a very short time",
    "reopen_conversation": false
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
issue_resolvedMandatory boolean Specifies whether the issue associated with the conversation is resolved.
Valid values: true, false
ratingMandatory if the value of issue_resolved is true. integer CSAT score that the customer provides.
Valid values: 1 - 5
additional_feedback string Feedback provided as part of the CSAT survey.
reopen_conversation boolean Specifies whether to reopen the conversation.
Valid values: true, false
Note: A conversation cannot be reopened if issue_resolved is true.
Response

A successful request returns 201 Created along with the created csat object.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
{
    "csat_response_id": 741611473053925,
    "created": 1683812688548,
    "additional_feedback": "Issue was resolved in a very short time",
    "rating": 5,
    "interaction_id": "463700702359153-1615963379263",
    "conversation_id": "7bc48e9b-e75d-4e67-a96c-384396ef8631",
    "issue_resolved": true,
    "csat_attributer_id": 464464627971760,
    "app_id": 587545534469,
    "reopen_conversation": false
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
csat_response_id integer Identifier of the csat object, auto-generated when a CSAT rating record is created in the Freshchat system.
created integer Timestamp of when the CSAT rating record is created in the Freshchat system, specified in epoch format.
additional_feedback string Feedback that the customer provides as part of the CSAT survey.
rating integer CSAT score that the customer provides.
Possible values: 1 - 5
interaction_id string Identifier of the interaction, auto-generated when a conversation is initiated by a user or an agent. An interaction is a conversation from the time it is initiated to the time the conversation is resolved. If the conversation is reopened, a new interaction_id is assigned to the conversation.
conversation_id string Identifier of the conversation object, auto-generated when a conversation record is created in the Freshchat system.
issue_resolved boolean Specifies whether the issue associated with the conversation is resolved.
Valid values: true, false
csat_attributer_id integer Identifier of the agent to whom the conversation was assigned at the time of resolution.
app_id integer Auto-assigned organization-level identifier that helps integrate applications with Freshchat.
reopen_conversation boolean Specifies whether the conversation is reopened based on the CSAT rating provided.
Valid values: true, false

Images

As part of Freshchat conversations, agents can send and receive images. The agents can upload, store, and retrieve the images from a file system (backed by an S3 bucket) in Freshchat. This API enables uploading an image to an S3 bucket linked to the Freshchat account.

Endpoints

POST /images/upload

Upload an image

Uploads an image from the file path passed in the request and returns a pre-signed URL to access the image from the S3 bucket to which the image is uploaded.

post
v2/images/upload
Sample request | Curl
Copied Copy 
1
2
3
4
5
curl -X POST "https://<account>.freshchat.com/v2/images/upload" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJraWQiOiJjxxxk6xsM" 
        -H "Content-Type: multipart/form-data" 
        -F "image=@C:\Users\abc\Desktop\sample_image.PNG;type=image/png"
EXPAND ↓
The request body parameter
Example 
1
image=@C:\Users\abc\Desktop\sample_image.PNG;type=image/png
EXPAND ↓
Attributes
Attribute Name Data Type Description
imageMandatory multipart formData
Note: Ensure that the Content-Type request header is set to multipart/form-data		 [Part1] image part specifies the location from which the media file is retrieved for upload.
[Part2] type part specifies the media format.
Response

A successful request returns 201 Created along with a pre-signed URL from which the image can be retrieved.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "id": "fe2c7241-46b5-42c2-8ef4-f814a79f2768",
    "content_type": "image/png",
    "height": 345,
    "name":"img_h7nco0371v_7c2bf570.png",
    "thumbnail": {
        "url":"https://fc-bkt-00.s3.amazonaws.com/f5axxxc4f1/f_marketingPicThumb/u_1710xxx23d7/img_coak8f09m7_38bb429e3b9428xxx4e11f.jpeg",
        "content_type": "image/jpeg",
        "width": 400,
        "height": 309
    },
    "url":"https://fc-bkt-00.s3.amazonaws.com/f5axxxc4f1/img_h7nco0371v_7c2bf570.png",
    "width": 446
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the image object, auto-generated when an image is uploaded to the S3 bucket.
content_type string Format of the uploaded file. For example, image/png.
height integer Original height of the image uploaded.
name string Identifier of the uploaded image.
thumbnail object Details of the image that can be retrieved from the S3 bucket.
Attributes of the object:
url (string): S3 bucket from where the uploaded image can be retrieved.
content_type (string): Format of the image on retrieval. For example, image/jpeg.
width (integer): Width of the compressed image.
height (integer): Height of the compressed image.
url string S3 bucket where the uploaded image is stored in its original format.
width integer Original width of the uploaded image.

Roles

An agent's access privileges within the Freshchat system is based on the role assigned to the agent. Each role comes with a predefined set of privileges. In addition to the default roles such as account admin, admin, support manager, and support agent can configure custom roles with customized privileges in the Freshchat system. For more information on roles, see Roles and permissions in Freshchat.

Endpoints

GET /roles

The role object

Example 
1
2
3
4
5
6
{
    "id": "ACCOUNT_ADMIN",
    "name": "Account Admin",
    "is_custom_role": false,
    "description": "Primary stakeholder of the business account"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Identifier of the role object, auto-generated when a new role is configured in the Freshchat system.
name string Name of the role.
is_custom_role boolean Specifies whether the role is a custom role.
Possible values: true, false
description string Meaningful description about the role.

List all roles

Retrieves a list of all valid roles configured in the Freshchat system.

get
/v2/roles
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/roles?page=1&items_per_page=10&sort_order=asc&sort_by=name" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJraWQiOiJjxxxskdz2Dkl-I"
EXPAND ↓
Response

A successful request returns 200 OK along with all roles’ details, as an array. Each array entry is a role object with the corresponding attributes. The response data is limited by the valid query parameters passed in the request. The response also contains response parameters pertaining to pagination.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
    "roles": [
    {
        "id": "ACCOUNT_ADMIN",
        "name": "Account Admin",
        "is_custom_role": false,
        "description": "Primary stakeholder for the business account."
    },
    {
        "id": "ADMIN",
        "name": "Admin",
        "is_custom_role": false,
        "description": "Stakeholder with all Admin permissions."
    },
    {
        "id": "AGENT",
        "name": "Agent",
        "is_custom_role": false,
        "description": "Account partner with agent level permissions."
    },
    {
        "id": "8bee5c99-2695-436c-a266-5cb310190406",
        "name": "Internal agent",
        "is_custom_role": true,
        "description": "Account executive identified as an internal agent."
    }],
    "pagination": {
        "total_items": 37,
        "total_pages": 4,
        "current_page": 1,
        "items_per_page": 10
    },
    "links": {
        "next_page": {
            "href": "/v2/roles?sort_by=name&items_per_page=10&sort_order=asc&page=2",
            "rel": "role",
            "type": "GET"
        },
        "first_page": {
            "href": "/v2/roles?sort_by=name&items_per_page=10&sort_order=asc&page=1",
            "rel": "role",
            "type": "GET"
        },
        "last_page": {
            "href": "/v2/roles?sort_by=name&items_per_page=10&sort_order=asc&page=4",
            "rel": "role",
            "type": "GET"
        }
    }
}
EXPAND ↓

Outbound-messages

A business can use its Freshchat account and send messages, in predefined formats, to clients who opt for notifications. These messages could be information about deliveries, purchases, payments, appointments, and so on.

The templated message that a business sends to its clients can be a plain text message, a rich media templated message consisting of a header and body or an interactive message with Call-to-Action and Quick Reply buttons attached to the text message or rich-media message. The rich media header can consist of an image, video, document attachment, and title with any number of variables. The body can consist of a text with any number of variables. A business defines the message template, with placeholders for rich media and parameters that can be populated when the message is sent, and submits the template to Freshchat. Freshchat seeks approval from the third-party provider whose services are used to send the templated message to clients. After the provider approves the template, Freshchat provides the template identifier and namespace obtained from the third-party provider to the business. The business can use this data and the Freshchat outbound-messages API to populate the message template with actual data and send the message to the business user. For information on the process around message template submission and approval, see WhatsApp Proactive Messages.

Note: For more information on interactive message templates, see Sending Interactive Message Templates.

Endpoints

POST /outbound-messages/whatsapp
GET /outbound-messages

The outbound message object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
    "message_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9",
    "from": {
      "phone_number": "+919999999999"
    },
    "provider": "whatsapp",
    "to": [
    {
      "phone_number": "+919999999999"
    }
     ],
    "data": {
      "message_template": {
        "storage": "conversation",
        "template_name": "shipping_update",
        "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
        "language": {
          "policy": "deterministic",
          "code": "en_US"
        },
        "rich_template_data": {
          "body": {
            "params": [{
              "data": "Username"}
            ]
          }
        }
      }
    },
    "request_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9",
    "status": "Failed",
    "created_on": 1566970961,
    "failure_code": "OBM001",
    "failure_reason": "no template exists"
  }
EXPAND ↓
Attributes
Attribute Name Data Type Description
message_id (response attribute) string Identifier of an outbound message, auto-generated when a request to send an outbound message is triggered.
from mandatory user handle object Business number integrated with the Freshchat account, from which the message is sent.
providermandatory string Channel through which messages are received by the client.
Possible value: whatsapp
tomandatory array of user handle objects List of recipient’s numbers or handles to which the message is sent.
datamandatory data object Data posted to the recipient, specified as a message template object.
request_id(response attribute) string Identifier of the request to send an outbound message, auto-generated when the request is triggered. A successful API request to send outbound messages, returns this attribute as part of the response object. Further API requests can use the returned value to identify the request and retrieve all outbound messages sent through the processing of the request.
status mandatory string Status of the message.
Possible values (enum):
Accepted: Message receipt is acknowledged by the recipient.
Sent: Message is sent to the recipient.
Delivered: Message is delivered to the recipient.
Failed: Message delivery failed. If status is failed, the failure_code and failure_reason attributes are present in the response object.
failure_code(response attribute) string Code that can be cross-referenced with failure_reason to understand why the request to send an outbound message failed.
failure_reason(response attribute) string Reason why the request to send an outbound message failed.
created_on(response attribute) integer Timestamp of when the request to send the message is triggered, specified in the epoch format.

Attributes of the user handle object

Attribute Name Data Type Description
phone_number string Number from or to which messages are sent.

Attributes of the message template object

Attribute Name Data Type Description
storage string Specifies whether the templated message sent to the user is reconstructed for the agent, in a conversation.
When a user replies to a templated message, the response is sent as a message to the Freshchat account. The templated message sent to the user is reconstructed and displayed in the conversation, based on the value of storage.
Possible values:
  • none (string): Details of the templated message sent to the user are not displayed in the conversation. Instead, the default message, Proactive message was sent to the user is displayed in the conversation.
  • conversation (string): The templated message sent to the user is reconstructed in the conversation. The user’s chosen reply to the templated message is also displayed in the conversation.
    Note: When the storage attribute value is conversation, the templated message is reconstructed for the agent only if a user replies to the templated message within 30 days from when the message is sent.
template_namemandatory string Identifier of a template within a namespace.
This is the template name that Freshchat submits to WhatsApp, on behalf of the business that uses Freshchat.
For information on the process around message template submission and approval, see WhatsApp Proactive Messages.
namespacemandatory string Unique identifier of a business’s Whatsapp account.
This is the namespace generated by Whatsapp and shared with Freshchat after the business’s message templates are approved by Whatsapp. It is available in the Message templates section of the customer's WhatsApp Business Account (WABA).

For information on the process around message template submission and approval, see WhatsApp Proactive Messages.
languagemandatory language object Language in which the message is sent.
To send messages in a language other than English, the business must submit the other language’s template content to Freshchat. Freshchat would submit the template content to WhatsApp and return the approved template ID and namespace to the business.
For more information, see WhatsApp Proactive Messages.
Attributes of the language object:
  • policy (string): The language policy used for sending messages based on language or locale.
    Possible value:
    deterministic: Message is delivered in the specified language irrespective of the language or locale of the device the message is delivered to.
  • code (string): Code corresponding to the supported languages for WhatsApp Proactive Messaging templates.
template_dataDEPRECATED array of template data objects Deprecation notice: This attribute is deprecated and exists only for backward compatibility.
To specify the values that are used to populate the variable parameters in a plain text message, use the rich_template_data attribute with the rich_template_data.type value set to text.
rich_template_dataMANDATORY rich media template data object Components, such as image, video, or document attachment, that are used to populate the header section of a templated message and the variable parameters that are used to populate the placeholders defined in the title and body text of the templated message, specified in a format that follows the WhatsApp proactive messaging guidelines.
Attributes of the rich media template data object:
  • header (object): Header components, specified as an object with the following attributes:
    • type (string): Type of the header component. For example, text, image, document, video.
    • media_url (string): Link to the location from where the image, video, or document to be attached is fetched and populated in the header section.
    • params (array of data objects): Values used to populate the variable parameters in the message title, if header.type is text.
  • body (object): Values used to populate the variable parameters in the body section of the predefined template message, specified as an object of the following format:

    {
    "params": [
    {"data": "<variableParam1>"},
    {"data": "<variableParam2>"}
    ]
    }

Example:
The template message is: Hi {{1}}, your order no. {{2}} has been placed.
The rich_template_data.body is:

{
"params": [
{"data": "John Doe"},
{"data": "IDxyz"}
]
}

The message body sent to the business user’s Whatsapp number is:
Hi John Doe, your order no. IDxyz has been placed.
Examples

  • In the request to send a plain text templated message, the outbound message object used as the request payload is as follows: 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "message_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9",
  "from": {
    "phone_number": "+919999999999"},
  "provider": "whatsapp",
  "to": [{
    "phone_number": "+919999999999"
    }],
  "data": {
    "message_template": {
      "storage": "conversation",
      "template_name": "shipping_update",
      "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
      "language": {
        "policy": "deterministic",
        "code": "en_US"
      },
        "rich_template_data": {
          "body": {
            "params": [{
              "data": "Username"}
          ]
        }
      }
    }
  },
  "request_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9",
  "status": "Failed",
  "created_on": 1566970961,
  "failure_code": "OBM001",
  "failure_reason": "no template exists"
}
EXPAND ↓

  • In the request to send templated message with image and text, the outbound message object used as the request payload is as follows: 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "from": {
    "phone_number": "+919999999999"
  },
  "to": [{
    "phone_number": "+919999999999"
  }],
  "data": {
    "message_template": {
      "storage": "none",
      "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
      "template_name": "shipping_update_1",
      "language": {
        "policy": "deterministic",
        "code": "en_US"
      }
      "rich_template_data": {
        "header": {
          "type": "image",
          "media_url": "https://sample.in/sample.jpg"
        },
        "body": {
          "params": [{
            "data": "Username"}
          ]
        }
      }
    }
  }
}
EXPAND ↓

  • In a request to send a plain text message with interactive buttons such as Quick Reply, the outbound message object sent as the request payload is as follows:
    Note: In the payload, as the data.message_template.storage value is none, the templated message is not reconstructed for the agent.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "from": {
    "phone_number": "+919999999999" },
  "provider": "whatsapp",
    "to": [{
      "phone_number": "+919999999999"}],
  "data": {
    "message_template": {
      "storage": "conversation",
      "template_name": "shipping_update_2",
      "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
      "language": {
        "policy": "deterministic",
        "code": "en_US"
      },
      "rich_template_data": {
        "body": {
          "params": [{
            "data": "Username"}
          ]
        }
      }
    }
  }
}
EXPAND ↓

  • In a request to send a rich-media templated message with interactive buttons, the outbound message object sent as the request payload is as follows:
    Note: In the payload, as the data.message_template.storage value is none, the templated message is not reconstructed for the agent.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "from": {
    "phone_number": "+919999999999"},
  "to": [{
    "phone_number": "+919999999999"}],
  "data": {
    "message_template": {
      "storage": "none",
      "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
      "template_name": " shipping_update_3",
      "language": {
        "policy": "deterministic",
        "code": "en_US"
      },
      "rich_template_data": {
        "header": {
          "type": "image",
          "media_url": "https://sample.in/sample.jpg"
        },
        "body": {
          "params": [{
            "data": "Username"}
          ]}
        }
      }
    }
  }
EXPAND ↓

  • In a request to send a rich-media templated message with interactive call to action buttons, the outbound message object sent as the request payload is as follows:
    Note: In the payload, as the data.message_template.storage value is none, the templated message is not reconstructed for the agent.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "from": {
    "phone_number": "+919999999999"},
  "to": [{
    "phone_number": "+919999999999"}],
  "data": {
    "message_template": {
      "storage": "none",
      "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
      "template_name": " shipping_update_4",
      "language": {
        "policy": "deterministic",
        "code": "en_US"
      },
      "rich_template_data": {
        "header": {
          "type": "image",
          "media_url": "https://sample.in/sample.jpg"
        },
        "body": {
          "params": [{
            "data": "Username"}
          ]}
        }
      }
    }
  }
EXPAND ↓

  • A Message Template Admin can opt for a Visit Website type Call-to-Action button in message template and define a placeholder to be post-fixed to the URL. Note that only one placeholder can be added.
    Example:https://www.freshworks.com/{{1}}


    Configure: Choose the URL type as 'Dynamic' in order to provide a dynamic placeholder when redirecting.


    Preview of the modified template

    Redirection: On clicking the URL, the placeholder is replaced and opens the fully qualified URL.



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "from": {
    "phone_number": "+919999999999"
  },
  "to": [
    {
      "phone_number": "+919999999999"
    }
  ],
  "data": {
    "message_template": {
      "storage": "none",
      "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
      "template_name": "sample_dynamic_button",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "rich_template_data": {
        "button": {
          "subType": "url",
          "params": [
            {
              "data": "live-chat-software"
            }
          ]
        }
      }
    }
  }
}
EXPAND ↓

Send outbound messages

Creates a request to send whatsapp messages to users.
Note: If the request to send a templated message contains an incorrect template name, the request fails. If a template with the name specified in the request is approved, you can send a message with the approved template name only after 30 minutes from the initial failure.

post
/v2/outbound-messages/whatsapp
Sample request | Curl
Copied Copy 
1
2
3
4
curl -X POST "https://api.freshchat.com/v2/outbound-messages/whatsapp"
-H "accept: application/json"
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpS216TTVXXX_U5X2A"
-d '{ "from": { "phone_number": "+919999999999" }, "provider": "whatsapp",  "to": [ { "phone_number": "+919999999999" } ], "data": { "message_template": {  "storage": "none",   "template_name": "hello_world", "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3f", "language": { "policy": "deterministic", "code": "en_US" },  "rich_template_data": { "header": { "type": "text",  "params": [ { "data": "John Doe" } ] },  "body": { "params": [ {"data": "XYZ"} ] } } } } }'
EXPAND ↓
Response
A successful request returns 202 along with the following response object.
Response object 
1
2
3
4
5
6
7
8
{
  "request_id": "0fcdd6b6-1f80-4643-a294-8e0625ce30dd",
  "request_process_time": "1",
  "link": {
    "rel": "string",
    "href": "string"
  }
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
request_idmandatory string System-generated identifier for the request.
request_process_timemandatory string Time taken to process the request, specified in seconds.
linkmandatory link object Reference to the request.
Attributes of the link object:
rel (string): Type of link relationship between the resource accessed by the href URL and the source from which the resource is referenced.
href (string): Reference to access the request.

List all outbound messages

Retrieves a list of all outbound messages sent from the Freshchat account.

get
/v2/outbound-messages
Query parameters

You can use the following query parameter to filter the bulk response data by request_id.

Parameter Name Description Example
request_id Identifier of the request to send an outbound message. A successful API request to send outbound messages, returns this attribute as part of the response object.
This parameter limits the bulk response to only outbound messages associated with a specific request.

GET /outbound-messages?request_id=5841b28c-7869-474f-9b25-c2b1ba9aa7b9
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://api.freshchat.com/v2/outbound-messages?request_id=5841b28c-7869-474f-9b25-c2b1ba9aa7b9"
-H "accept: application/json"
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpS216TTVXXX_U5X2A"
EXPAND ↓
Response

A successful request returns 200 along with all outbound messages from the Freshchat account, as an array. Each array entry is an outbound message object, with the corresponding attributes. The response data is limited by the query parameter passed in the request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "outbound_messages": [
    {
      "message_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9",
      "from": {
        "phone_number": "+919999999999"
      },
      "provider": "whatsapp",
      "to": {
        "phone_number": "+919999999999"
      },
      "data": {
        "message_template": {
          "storage": "none",
          "template_name": "hello_world",
          "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
          "language": {
            "policy": "deterministic",
            "code": "en_US"
          },
          "rich_template_data": {
            "header": {
              "type": "image",
              "media_url": "https://sample.in/sample.jpg"
            },
            "body": {
              "params": [
                {
                  "data": "John Doe"
                }
              ]
            }
          }
        }
      },
      "request_id": "5841b28c-7869-474f-9b25-c2b1ba9aa7b9",
      "status": "Failed",
      "created_on": 1566970961,
      "failure_code": "OBM001",
      "failure_reason": "no template exists"
    }
  ]
}
EXPAND ↓

Reports

Reports help obtain certain raw metrics related to team performance, agent availability, conversation overview, customer satisfaction, and resolution types. Collectively, the reports cover all metrics related to the entire interaction life cycle and agent activity. You can extract the Freshchat reports with unprocessed data and create custom reports or populate data in a Business Intelligence (BI) tool.

Endpoints

POST /reports/raw
GET /reports/raw/{id}

Extract a report

Submits a request to extract a report. The response object contains a unique identifier of the report and a reference to the requested report.

post
/reports/raw
Request object 
1
2
3
4
5
6
{
    "start": "2020-01-23T00:30:00.000Z",
    "end": "2020-01-23T18:59:59.000Z",
    "event": "Conversation-Group-Assigned",
    "format": "csv"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
start string Starting date for report generation, specified in the UTC format. Must not be a date earlier than 15 months from the current date.
end string Ending date for report generation, specified in the UTC format. Must not be a date later than a month from the starting date.
event string Name of the event whose data is to be extracted.
Possible values:
Chat-Transcript: The raw report lists all chat transcripts (conversations and the corresponding messages) created within a time frame of 24 hours. For this report, the end value should not be more than 24 hours from the start value.
Conversation-Created: The raw report lists the details of all conversations created within a time frame. This helps track the volume of incoming conversations.
Message-Sent: The raw reports lists the details of all messages sent within a time frame. This helps track the volume of agent activity.
Conversation-Resolved: The raw reports lists the details of all conversations resolved within a time frame. This helps track the volume of resolved conversations.
Conversation-Resolution-Label: The raw report lists the details of all resolution labels attached to a conversation when the conversation is resolved. This helps track the trend in conversation volumes by aggregating the percentage of conversations belonging to a specific category and sub-category of resolution.
For information on how resolution labels can help identify trends in customer queries, see Conversation labels and label reports.
CSAT-Score: The raw report lists all customer satisfaction ratings received agent-wise, within a specific time frame. This helps monitor the customer satisfaction levels and also generate useful actionable metrics such as the number of unsatisfactory conversations.
First-Response-Time: The raw report tracks the time agents and groups take to send the first response to a customer message. This helps evaluate productivity and team performance.
Response-Time: The raw report tracks the time agents and groups take to reply to a message in a conversation. This helps evaluate productivity and team performance.
Resolution-Time: The raw report tracks the time agents and groups take to resolve a conversation assigned to the agent or group. This helps evaluate productivity and team performance.
Conversation-Agent-Assigned: Tracks the time taken to assign a conversation to an agent.
Conversation-Group-Assigned: Tracks the time taken to assign a conversation to a group.
Agent-Activity: Tracks agent activity in the Freshchat dashboard.
Agent-Intelliassign-Activity: Tracks agent activity when a conversation is auto-assigned through IntelliAssign.
Conversation-Activity: The raw report lists the details of all conversations created, reopened and resolved within a time frame. This helps track the volume of incoming and resolved conversations. The report also tracks the time taken to assign a conversation to an agent.
Classic: The raw report lists the details of an interaction within a time frame of 24 hours. For this report, the end value should not be more than 24 hours from the start value.
Agent-performance: Tracks the agent performance within a time frame of 24 hours. For this report, the end value should not be more than 24 hours from the start value.
format string Format in which the reports are to be extracted.
Possible value: csv

The various csv reports and their parameters are as follows.

Chat-Transcript report
  • conversation_id:: System generated identifier of the conversation that is created. The conversation_id is the same for the entire conversation thread. A chat transcript contains all conversations that happened in the specified time window.
  • conversation_url: URL using which agents and teams can access the conversation from the inbox.
  • customer_id: System generated identifier of the user who initiated the interaction.
  • detailed_message_type (Used only for internal purposes): Type of message in the conversation. For example, 1 (message sent by the agent or user), 2 (message sent by bot), 1000 (private note added to the conversation), and so on.
  • interaction_raw_id: System generated identifier of an interaction - a conversation from the time the first message is created to the time the conversation is closed, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • message_id: System generated identifier of a message in a conversation. Each message in an interaction would have a unique identifier.
  • message_type: Message type based on the actor who sends a message. Possible values: normal (sent by user or agent), private (private message sent by user or agent), and system (system generated message).
  • message_parts: Different parts of a message posted to the conversation - plain text, images, or url buttons. The message can be a combination of these attributes. In the report, message_parts field is an array of JSON objects. For more information, see the message part object.
  • created_time: Timestamp of when the message is sent, specified in the UTC format.
  • actor_id: System generated identifier of the entity who sends the message to the conversation. If the message is a user message, the actor_id is the user id that is auto-generated when the user is created in the Freshchat system. If the message is an agent’s message, the actor_id is the agent id that is auto-generated when the agent is configured in the Freshchat system.
  • actor_type: Name of the entity who initiated the conversation. Possible values: USER, AGENT, SYSTEM, and BOT.
  • actor_sub_entity: When actor_type is SYSTEM, actor_sub_entity identifies the routing type, such as assignment rules, Intelliassign, topic-group mapping, and so on, that causes the message to be assigned to a specific agent/group. Possible values: intelliAssign, rule, api, dsat (system assignment is a result of the dissatisfied customer analysis), and channel (system assignment is a result of topic-group mapping).
  • actor_email: Email id of the agent or user who sent the message. For system messages, an empty value is returned.
  • actor_phone: Phone number of the user who sent the message. For system messages, an empty value is returned.
  • actor_first_name: First Name of the agent or user who sent the message. For system messages, an empty value is returned.
  • actor_last_name: Last Name of the agent/ user who sent the message. For system messages, an empty value is returned.
  • message_source: Source from which the message in the conversation is initiated. Possible values: web, system, mobile, api, freshdesk, zendesk, smooch, and facebook_native.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • channel_name: Name of the topic, such as Billing or Sales, under which the conversation is created. Topics channelise customers to the appropriate groups.

Conversation-Created report
  • channel_name: Name of the topic, such as Billing or Sales, under which the conversation is created. Topics channelise customers to the appropriate groups.
  • reopened: If true, specifies that the conversation is a reopened conversation.
  • actor_type: Name of the entity who initiated the conversation. Possible values: USER, AGENT, SYSTEM, and BOT.
  • group_name: Name of the group to which the created conversation is assigned. As soon as they are created, conversations can be auto-assigned based on topic-group mapping, IntelliAssign, and so on.
  • reopen_cause: System generated reason for reopening the conversation. Possible values: AGENT_REOPEN, USER_MESSAGE, CUSTOMER_DISSATISFACTION, BOT, and FREDDY_BOT.
  • created_at: Timestamp of when the conversation is created, specified in the UTC format.
  • interaction_id: System generated identifier of an interaction - a conversation from the time the first message is created to the time the conversation is closed. If the conversation is reopened a new interaction_id is assigned to the conversation.
  • conv_url: URL using which agents and teams can access the conversation from the inbox.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • conversation_id: System generated identifier of the conversation that is created. The conversation_id is the same for the entire conversation thread irrespective of the number of resolutions and reopenings that happen.
  • is_conv_offline: If true, specifies that the conversation is created or reopened outside business hours, through Freshchat’s Offline Experience workflow.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Message-Sent report
  • channel_name: Name of the topic, such as Billing or Sales, under which the message in a conversation is sent.
  • actor_sub_type: When actor_type is SYSTEM, actor_sub_type identifies the routing type, such as assignment rules, Intelliassign, topic-group mapping, and so on, that causes the message to be assigned to a specific agent/group. Possible values: intelliAssign, rule, api, dsat, and channel.
  • reopened: If true, specifies that the conversation to which the message is sent is a reopened conversation.
  • actor_type: Name of the entity who sends the message to the conversation. Possible values: USER, AGENT, SYSTEM, and BOT.
  • group_name: Name of the group from which an agent responds through the message sent or is expected to respond to a user message.
  • actor_name: Name of the entity who sent the message. If the message is a user message, the actor_name is the user’s name. If the message is an agent’s message, the actor_name is the agent’s name. If the message is sent by a system or BOT, the actor_name is a system generated value.
  • created_at: Timestamp of when the message is sent, specified in the UTC format.
  • interaction_id: System generated identifier of the interaction (a conversation from the time the first message is created to the time the conversation is closed) to which the message sent belongs.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp of when the conversation is created format.
  • group_id: System generated identifier of the group to which the conversation is assigned. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • conversation_id: System generated identifier of the conversation to which the message sent belongs.
  • actor_id: System generated identifier of the entity who sends the message to the conversation. If the message is a user message, the actor_id is the user id that is auto-generated when the user is created in the Freshchat system. If the message is an agent’s message, the actor_id is the agent id that is auto-generated when the agent is configured in the Freshchat system.
  • channel_id: System generated identifier of the topic under which the message is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Conversation-Resolved report
  • channel_name: Name of the topic under which the conversation that is resolved is created.
  • reopened: If true, specifies that the conversation that is resolved is a reopened conversation.
  • actor_type: Name of the entity who resolved the conversation. Possible values: AGENT, SYSTEM, and BOT.
  • resolve_type: Identifier of the entity who resolved the conversation. Possible values: AGENT_RESOLVE, AUTO_RESOLVE, BOTS_RESOLVE, and FREDDY_BOT_RESOLVE
  • agent_name: Name of the agent to whom the conversation is assigned for resolution.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution.
  • group_name: Name of the group to which the conversation is assigned for resolution or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • actor_name: Name of the entity who resolved the conversation. If the conversation is resolved by an agent, actor_name is the agent’s name.
  • created_at: Timestamp of when the conversation that is assigned for resolution is created, specified in the UTC format.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • actor_belongs_to_group: If true, specifies that the actor who resolved the conversation belongs to the group to which the conversation is assigned.
  • conversation_id: System generated identifier of the conversation that is assigned for resolution.
  • actor_id: System generated identifier of the entity that resolved the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Conversation-Resolution-Label report
  • channel_name: Name of the topic under which the conversation that is resolved is created.
  • reopened: If true, specifies that the conversation that is resolved is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution.
  • actor_type: Name of the entity who resolved the conversation. Possible values: user, AGENT, SYSTEM, and BOT.
  • label_sub_category_id: System generated identifier for the resolution label sub-category. When a sub-category is configured in the Freshchat system, a label_sub_category_id is auto-generated and assigned to the sub-category.
  • group_name: Name of the group to which the conversation is assigned for resolution or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • user_name: Name of the user who is involved in the conversation with the agent.
  • actor_name: Name of the entity who resolved the conversation. If the message is resolved by an agent, actor_name is the agent’s name.
  • label_category_name: Meaningful name of the resolution label configured in the Freshchat system. When processing the raw data from this report, conversations can be grouped by labels to study the volume of conversations belonging to specific categories.
  • created_at: Timestamp of when the resolution label is attached to the conversation and the conversation is resolved.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • actor_belongs_to_group: If true, specifies that the actor who resolved the conversation belongs to the group to which the conversation is assigned.
  • conversation_id: System generated identifier of the conversation that is assigned for resolution.
  • label_category_id: System generated identifier for the resolution label primary category. When a label is configured in the Freshchat system, a label_category_id is auto-generated and assigned to the label.
  • actor_id: System generated identifier of the entity that resolved the conversation.
  • abel_sub_category_name: Meaningful name of the resolution label’s sub-category specified when the label is configured in the Freshchat system.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • labelled_by_type: Identifier of the entity who attached the pre-configured label to the conversation and resolved the conversation. Possible values: AUTO_RESOLVE and AGENT.
    •   Note: Freshchat customers can associate resolution labels for auto-resolution rules.

CSAT-Score report
  • channel_name: Name of the topic under which the conversation for which the user provided a CSAT rating is created.
  • reopened: If true, specifies that the conversation for which the user provided a CSAT rating is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution.
  • csat_id: System generated identifier of the CSAT setting configured for the business account. When a CSAT setting is configured in a Freshchat system, a csat_id is auto-generated and assigned to the setting.
  • csat_submitter_user_name: Name of the user who provides the CSAT rating for the agent who resolved the conversation.
  • csat_submitter_user_id: System generated identifier of the user who provides the CSAT rating. When a user is created in the Freshchat system, a user_id is auto-generated and associated with the user.
  • group_name: Name of the group to which the conversation is assigned for resolution or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • actor_name: Name of the entity who resolves the conversation and thereby triggers the CSAT survey.
  • created_at: Timestamp of when the CSAT rating is provided.
  • has_response: If true, specifies that the user has provided additional comments along with the rating.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved. CSAT survey is triggered at the end of every interaction, if Customer Satisfaction Rating is enabled for the business account.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp of when the conversation is created format.
  • issue_resolved: If true, specifies that the user who provided the CSAT rating has confirmed that the issue associated with the conversation has been resolved.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • actor_belongs_to_group: If true, specifies that the actor who resolves the conversation and thereby triggers the CSAT survey, belongs to the group to which the conversation is assigned for resolution.
  • conversation_id: System generated identifier of the conversation for which the user provides the CSAT rating.
  • csat_reopen: If true, specifies that the conversation is reopened based on the CSAT rating.
  • csat_response: Comment provided by the user as part of the rating.
  • actor_id: System generated identifier of the entity who resolved the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • value: Numeric value of the CSAT rating. Possible values: 0 - 5

First-Response-Time report
  • channel_name: Name of the topic under which the conversation is created.
  • reopened: If true, specifies that the conversation is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution. If there is a response to the message that initiated the conversation before assignment to an agent, in the report, this field value is empty.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution. If there is a response to the message that initiated the conversation before assignment to an agent, in the report, this field value is empty.
  • group_name: Name of the group to which the conversation is assigned for resolution. If there is a response before assignment, this field value is empty.
  • actor_name: Name of the entity who responds to the conversation.
  • created_at: Timestamp of when the first response is received for the conversation.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • total_first_response_time_in_seconds: Time taken for the conversation to receive the first response, without considering the business hours set up for the organization, specified in seconds.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If there is a response before assignment, this field value is empty.
  • actor_belongs_to_group: If true, specifies that the actor who responded to the conversation, belongs to the group to which the conversation is assigned for resolution. If there is a response before assignment, this field value is false.
  • conversation_id: System generated identifier for the conversation.
  • value_in_seconds: Time taken for the conversation to receive the first response, taking into consideration the business hours set up for the organization, specified in seconds.
  • actor_id: System generated identifier of the actor who responds first to the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Response-Time report
  • channel_name: Name of the topic under which the conversation is created.
  • actor_sub_type: When actor_type is SYSTEM, actor_sub_type identifies the routing type, such as assignment rules, Intelliassign, topic-group mapping, and so on, that causes the conversation to be assigned to a specific agent/group. Possible values: intelliAssign, rule, api, dsat, and channel.
  • reopened: If true, specifies that the conversation is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • actor_type: Name of the entity who responds to the user messages in the conversation. Possible values: AGENT, SYSTEM, and BOT.
  • group_name: Name of the group to which the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • actor_name: Name of the entity who responds to user messages in the conversation. If the actor_type is AGENT, this is the agent’s name.
  • created_at: Timestamp of when the conversation is resolved, specified in the UTC format.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • actor_belongs_to_group: If true, specifies that the actor who responded to the user messages in the conversation, belongs to the group to which the conversation is assigned for resolution. If there is no specific assignment, this field value is false.
  • conversation_id: System generated identifier for the conversation.
  • value_in_seconds: Response time is the time taken to send reply messages for the user messages in the conversation. This field specifies the sum of all response times recorded for an interaction.
  • actor_id: System generated identifier of the actor who responds to the user messages in the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Resolution-Time report
  • channel_name: Name of the topic under which the conversation is created.
  • actor_sub_type: Routing type, such as assignment rules, Intelliassign, topic-group mapping, and so on, that causes the conversation to be assigned to a specific agent/group.
  • reopened: If true, specifies that the conversation is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report this field is empty.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report this field is empty.
  • actor_type: Name of the entity who interacts with the user, in the conversation. Possible values: AGENT, SYSTEM, and BOT.
  • group_name: Name of the group to which the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report this field is empty.
  • actor_name: Name of the entity who interacts with the user, in the conversation. If the actor_type is AGENT, this is the agent’s name.
  • created_at: Timestamp of when the conversation is resolved, specified in UTC format.
  • interaction_id: System generated identifier of an interaction - the conversation from the time the first message is created to the time the conversation is resolved.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If there is no specific assignment for a conversation, in the report, this field is empty.
  • actor_belongs_to_group: If true, specifies that the actor who interacted with the user, belongs to the group to which the conversation is assigned for resolution. If there is no specific assignment, this field value is false.
  • conversation_id: System generated identifier for the conversation.
  • value_in_seconds: Average time taken to resolve the conversation, during an interaction.
  • actor_id: System generated identifier of the actor who interacts with the user, in the conversation.
  • channel_id: System generated identifier of the topic under which the conversation is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.

Conversation-Agent-Assigned report
  • conversation_id: System generated identifier of the conversation assigned to the agent.
  • interaction_id: System generated identifier of an interaction - a conversation from the time it is initiated to the time it is resolved.
  • channel_id: System generated identifier of the topic under which the assigned conversation is posted.
  • channel_name: Descriptive identifier of the topic.
  • group_id: System generated identifier of the group to which the agent to whom the conversation is assigned belongs.
  • group_name: Descriptive identifier of the group.
  • agent_id: Identifier of the agent to whom a conversation is assigned for resolution.
  • actor_id: Identifier of the entity that assigned the conversation to the agent.
  • actor_type: Descriptive identifier of the entity that assigned the conversation to the agent.
  • created_at: Timestamp of when the conversation is assigned to an agent, specified in the UTC format.
  • reassigned: If true, specifies that a conversation is reassigned to the agent.
  • value: Time taken to assign a conversation to an agent, specified in seconds.

Conversation-Group-Assigned report
  • conversation_id: System generated identifier of the conversation assigned to the group.
  • interaction_id: System generated identifier of an interaction - a conversation from the time it is assigned to a group to the time it is resolved.
  • channel_id: System generated identifier of the topic under which the assigned conversation is posted.
  • channel_name: Descriptive identifier of the topic.
  • group_id: System generated identifier of the group to which the conversation is assigned.
  • group_name: Descriptive identifier of the group.
  • actor_id: Identifier of the entity that assigned the conversation to the group.
  • actor_type: Descriptive identifier of the entity that assigned the conversation to the group.
  • created_at: Timestamp of when the conversation is assigned to the group, specified in the UTC format.
  • reassigned: If true, specifies that a conversation is reassigned to the group.
  • value: Time taken to assign a conversation to a group, specified in seconds.
  • reopened: If true, specifies that the conversation assigned to the group is a reopened conversation.
  • agent_name: Name of the agent to whom the conversation is assigned for resolution.
  • agent_id: System generated identifier of the agent to whom the conversation is assigned for resolution.
  • actor_name: Name of the entity that assigned the conversation to the group.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.

Agent-Activity report
  • agent_name: Name of the agent whose activity on the Freshchat dashboard is tracked.
  • agent_id: System generated identifier of the agent.
  • activity_type: Type of activity, agent logging in (online) or logging off (offline), that triggered the agent activity data to be recorded.
  • created_at: Timestamp of when an agent logs in or logs off, specified in the UTC format.

Agent-Intelliassign-Activity report
  • agent_name: Name of the agent to whom a conversation is assigned through IntelliAssign.
  • agent_id: System generated identifier of the agent.
  • activity_type: Type of activity, agent logging in (active), logging off (inactive), or setting a custom status, that triggered the agent activity data to be recorded.
  • created_at: Timestamp of when an agent logs in or logs off, specified in the UTC format.

    • If the custom activity state feature (in beta) is enabled for a business account that uses Freshchat, the business can configure custom statuses, such as Away, In a meeting, and so on, for their agents to use. The following two fields are available as part of the Agent-Intelliassign-Activity report only if this feature is enabled for an account.

  • agent_status: Custom status set by the agent.
  • agent_status in seconds: Duration for which the agent has set the custom status, specified in seconds.

Conversation-Activity report
  • created_at: Timestamp of when the conversation is initiated, specified in the UTC format.
  • interaction_raw_id: System generated identifier of the interaction, specified in the 32-bit conversation id-timestamp (of when the conversation is created) format.
  • interaction_id: System generated identifier of an interaction - a conversation from the time the first message is created to the time the conversation is closed. If the conversation is reopened a new interaction_id is assigned to the conversation.
  • conversation_id: System generated identifier of the conversation that is created. The conversation_id is the same for the entire conversation thread irrespective of the number of resolutions and reopenings that happen.
  • user_id: System generated identifier of the user who initiated the conversation.
  • org_contact_id: Organization-level identifier of the user who sent the message.
  • assigned_at: Timestamp of when the conversation is assigned to an agent in the Freshchat system, specified in the UTC format.
  • agent_id: Identifier of the agent to whom a conversation is assigned for resolution.
  • org_agent_id: Organization-level identifier of the agent to whom a conversation is assigned for resolution.
  • resolved_at: Timestamp of when the conversation is resolved, specified in the UTC format.
  • resolved_by: System generated identifier of the agent who resolved the conversation.
  • group_id: System generated identifier of the group to which the conversation is assigned for resolution. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • org_group_id: Organization-level identifier of the group to which the conversation is assigned for resolution.
  • group_name: Name of the group to which the conversation is assigned for resolution or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • channel_id: System generated identifier of the topic under which the message is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • channel_name: Name of the topic under which the conversation is created.

Classic report
  • agent_reopen: If true, specifies that an agent reopened the conversation.
  • avg_response_time_secs: Average time an agent takes to respond to a message in the interaction, specified in seconds.
  • channel: Name of the topic, such as Billing or Sales, under which the conversation associated with the interaction is created.
  • channel_id: System generated identifier of the topic under which the conversation associated with the interaction is created. When a topic is created in the Freshchat system, a channel_id is auto-generated and assigned to the topic.
  • conversation_alias: Unique system generated identifier of the conversation (to which the interaction belongs) record in the Freshchat system.
  • conversation_id: System generated identifier of the conversation to which the interaction belongs.
  • created_timestamp: Timestamp of when the interaction is created in the Freshchat system, specified in the UTC format.
  • created_timestamp_millis: Timestamp of when the interaction is created in the Freshchat system, specified in milliseconds.
  • csat_agent: Name of the agent who resolved the conversation and thereby triggered the CSAT survey.
  • csat_agent_id: Email address of the agent who resolved the conversation and thereby triggered the CSAT survey.
  • csat_group: Name of the group (to which the agent who resolved the conversation belongs) that resolved the conversation and triggered the CSAT survey.
  • csat_group_id: System generated identifier of the group to which the resolved conversation which triggered the CSAT survey is assigned. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs.
  • csat_issue_resolved: If true, specifies that the user who provided the CSAT rating has confirmed that the issue associated with the conversation is resolved.
  • csat_rating: Numeric value of the CSAT rating. Possible values: 0 - 5
  • csat_response: Comment provided by the user as part of the rating.
  • csat_timestamp: Timestamp of when a CSAT survey is triggered after the conversation associated with the interaction is resolved, specified in the UTC format.
  • csat_timestamp_millis: Timestamp of when a CSAT survey is triggered after a conversation associated with the interaction is resolved, specified in milliseconds.
  • first_assigned_group: Name of the group to which the interaction is first assigned.
  • first_assigned_group_id: System generated identifier of the group to which the interaction is first assigned for resolution. If the interaction is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group. This group_id is reflected as the first_assigned_group_id.
  • first_group_assigned_by: Assignment process that assigned the interaction to a group.
    Possible values: channel_group_mapping, api.
    When an interaction is assigned to a specific group based on the topic under which the associated conversation is created, the value of first_group_assigned_by is channel_group_mapping.
  • first_assigned_timestamp: Timestamp of when the interaction is first assigned to an agent, specified in the UTC format.
  • first_assigned_timestamp_millis: Timestamp of when the interaction is first assigned to an agent, specified in milliseconds.
  • first_assigned_by: Name of the entity who first assigned the interaction to an agent.
    Possible values: AGENT, BOT, and SYSTEM
  • first_assigned_to: Name of the agent to whom the interaction is first assigned.
  • first_assigned_to_id: System generated identifier of the agent to whom the interaction is first assigned.
  • first_group_assigned_timestamp: Timestamp of when the interaction is first assigned to a group, specified in the UTC format.
  • first_group_assigned_timestamp_millis: Timestamp of when the interaction is first assigned to a group, specified in milliseconds.
  • first_response_timestamp: Timestamp of when the first response is sent after the interaction is initiated, specified in the UTC format.
  • first_response_timestamp_millis: Timestamp of when the first response is sent after the interaction is initiated, specified in milliseconds.
  • first_response_time_secs: Time an agent takes to send the first response to an interaction after it is assigned, specified in seconds.
  • first_response_time_formatted: first_response_time_secs in the hh:mm:ss format.
  • first_responded_by: Name of the agent who first responded to the interaction.
  • first_responded_by_id: System generated identifier of the entity who first responded to the interaction.
  • first_response_assigned_agent: Email address of the agent to whom the conversation associated with the interaction was assigned, when the first response was sent.
  • first_response_assigned_agent_id: System generated identifier of the agent to whom the conversation associated with the interaction was assigned, when the first response was sent.
  • first_response_group: Name of the group to which the conversation associated with the interaction was assigned, when the first response was sent.
  • first_response_group_id: System generated identifier of the group to which the conversation associated with the interaction was assigned, when the first response was sent.
  • interaction_id: System generated identifier of an interaction - a conversation from the time the first message is created to the time the conversation is closed. If the conversation is reopened a new interaction_id is assigned to the conversation.
  • is_offline_conversation: If true, specifies that the interaction belongs to an offline conversation. A conversation is specified as an offline conversation when it is created, reopened, or a message is sent to it outside business hours.
  • last_response_timestamp: Timestamp of when the last response was sent to the interaction, specified in the UTC format.
  • lastresponse_timestamp_millis: Timestamp of when the last response was sent to the interaction, specified in milliseconds.
  • last_responded_by: Name of the agent who last responded to the interaction.
  • last_responded_by_id: System generated identifier of the agent who last responded to the interaction.
  • last_response_assigned_agent: Email address of the agent to whom the conversation associated with the interaction was assigned, when the last response was sent.
  • last_response_assigned_agent_id: System generated identifier of the agent to whom the conversation associated with the interaction was assigned, when the last response was sent.
  • last_response_assigned_group: Name of the group to which the conversation associated with the interaction was assigned, when the last response was sent.
  • last_response_assigned_group_id: System generated identifier of the group assigned to the conversation associated with the interaction when the last response was sent.
  • label_timestamp: Timestamp of when the resolution label is assigned to the conversation associated with the interaction, specified in the UTC format.
  • label_timestamp_millis: Timestamp of when the resolution label is assigned to the conversation associated with the interaction, specified in milliseconds.
  • label_applied_by: Email address of the agent who attached the pre-configured label to the conversation and resolved the conversation. For labels applied by the system, this value is null.
  • label_applied_by_id: System generated identifier of the entity who attached the pre-configured label to the conversation and resolved the conversation.
  • reassigns: Number of times the interaction is reassigned.
  • resolution_timestamp: Timestamp of when the conversation associated with the interaction is resolved, specified in the UTC format.
  • resolution_timestamp_millis: Timestamp of when the conversation associated with the interaction is resolved, specified in milliseconds.
  • resolution_time_secs: Time taken to resolve the conversation associated with the interaction, specified in seconds.
  • resolution_time_formatted: resolution_time_secs in the hh:mm:ss format.
  • resolved_by: Name of the entity who resolved the conversation associated with the interaction.
  • resolved_by_id: System generated identifier of the entity who resolved the interaction. When an agent resolves the conversation, the value of resolved_by_id is a valid agent_id.
  • resolution_assigned_agent: Email address of the agent to whom the interaction is assigned when the associated conversation is resolved.
  • resolution_assigned_agent_id: Identifier of the agent to whom the interaction is assigned when the associated conversation is resolved.
  • resolution_assigned_group: Name of the group to which the interaction is assigned when the associated conversation is resolved or the name of the group to which the agent to whom the conversation is assigned for resolution belongs.
  • resolution_assigned_group_id: System generated identifier of the group to which the interaction is assigned when the associated conversation is resolved. If the conversation is assigned to an agent, this is the identifier of the group to which the agent belongs. When a group is configured in the Freshchat system, a group_id is auto-generated and assigned to the group.
  • resolution_label: Name of the resolution label associated with the resolved interaction. Resolution labels help to track the trends in conversation volumes by aggregating the percentage of conversations belonging to a specific category and sub-category of resolution.
  • resolution_label_subcategory: Name of the resolution label’s sub-category associated with the resolved conversation to which the interaction belongs.
  • reopened: If true, specifies that the interaction is associated with a reopened conversation.
  • response_count: Number of responses the agent has sent in the interaction.
  • time_to_first_assign_secs: Time taken to first assign the interaction to an agent, specified in seconds.
  • time_to_first_response_from_create_secs: Time taken to send the first response after the interaction is initiated, specified in seconds.
  • time_to_first_response_from_create_formatted: time_to_first_response_from_create_secs in the hh:mm:ss format.
  • time_to_resolve_from_create_secs: Total time taken to resolve the interaction, specified in seconds.
  • time_to_resolve_from_create_formatted: time_to_resolve_from_create_secs in the hh:mm:ss format.
  • user_id: System generated identifier of the user who initiated the interaction.
  • user_name: Name of the user who initiated the interaction.
  • user_email: Email address of the user who initiated the interaction.
  • user_phone: Phone number of the user who initiated the interaction.
  • user_identifier: External identifier (reference) that the organization that uses Freshchat configures in Freshchat, to identify a user in another (external) system. Default value: null.
  • user_source: Source through which a user initiates the interaction. For example, FRESHBOT_WIDGET, WEBCHAT, and so on.

Agent-performance report
  • agent_id: System generated identifier of the agent.
  • agent_email: Email address of the agent.
  • agent_name: Name of the agent.
  • average_first_response_time_secs: Average time the agent takes to respond first to a conversation after it is assigned to the agent, specified in seconds.
  • average_response_time_secs: Average time the agent takes to respond to messages, specified in seconds.
  • average_handle_time_secs: Average time the agent takes to resolve a conversation, specified in seconds.
  • active_time_mins: Time for which the agent is active on IntelliAssign, specified in minutes.
  • average_csat_score: Average of all the CSAT scores received for resolved conversations assigned to the agent.
  • count_assigned: Number of conversations assigned to the agent for resolving.
  • count_resolved: Number of conversations that the agent resolves.
  • count_unique_resolved: Number of unique conversations resolved by the agent.
  • count_transfers_out: Number of conversations reassigned to other agents from the agent whose productivity is tracked through this report.
  • count_messages: Number of messages the agent sends in the specified time frame.
  • count_responses: Number of responses the agent sends in the specified time frame.
  • concurrency: Average number of conversations assigned to the agent for resolution simultaneously.
  • engagement_time_secs: Time for which the agent is in the assigned mode on Freshchat (that is, the agent is handling at least one conversation), specified in seconds.
  • online_time_mins: Time for which the agent has been online on Freshchat, specified in minutes.
  • report_start_time: Starting time of the report generation.
  • report_end_time: Ending time of the report generation.

Sample request | Curl
Copied Copy 
1
curl -X POST "https://api.freshchat.com/v2/reports/raw" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpS216TTVkenRIWmprdmdSY3VrVHgxTzJ2SFlTM0U5YmVJME9XbXRNR1ZzIn0.eyJqdGkiOiIyYTJiNTAwNi04NDk2LTQyMDctYWUyOC1mYzY4MTI4MGRkMmEiLCJleHAiOjE5MDM5Mzg1MTYsIm5iZiI6MCwiaWF0IjoxNTg4NTc4NTE2LCJpc3MiOiJodHRwOi8vaW50ZXJuYWwtZmMtdXNlMS0wMC1rZXljbG9hay1vYXV0aC0xMzA3MzU3NDU5LnVzLWVhc3QtMS5lbGIuYW1hem9uYXdzLmNvbS9hdXRoL3JlYWxtcy9wcm9kdWN0aW9uIiwiYXVkIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwic3ViIjoiN2VlYTUzNzctYzEzNy00MDI1LWFlYzgtMDhmZjE4MzkwN2EyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMjMyOTcwOWMtMTVjZS00NzA5LWE1MDctZjcwNGRmNmNmOTFmIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6W10sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJhZ2VudDp1cGRhdGUgbWVzc2FnZTpjcmVhdGUgYWdlbnQ6Y3JlYXRlIG1lc3NhZ2U6Z2V0IGRhc2hib2FyZDpyZWFkIHJlcG9ydHM6ZXh0cmFjdDpyZWFkIHJlcG9ydHM6cmVhZCBhZ2VudDpyZWFkIGNvbnZlcnNhdGlvbjp1cGRhdGUgdXNlcjpkZWxldGUgY29udmVyc2F0aW9uOmNyZWF0ZSBvdXRib3VuZG1lc3NhZ2U6Z2V0IG91dGJvdW5kbWVzc2FnZTpzZW5kIHVzZXI6Y3JlYXRlIHJlcG9ydHM6ZmV0Y2ggdXNlcjp1cGRhdGUgdXNlcjpyZWFkIHJlcG9ydHM6ZXh0cmFjdCBjb252ZXJzYXRpb246cmVhZCIsImNsaWVudElkIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguMTI5LjE1NyIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjEyOS4xNTcifQ.wE6Kec6OYhsD-CfW2YKf1XsIfGXhXMBZdlZuuACJ8HPukABaNRS3iMDmv0scPdIJJGKmN0w1_DIPQSwiigeA3Xb5NTVOFIKniICVMIwoBMcmeo3njJa4kFwkIo6dD-29xOG5B2flv9F-Nw0jX9qZ-G6oVRvYUS6Ra4-MISLIbe6qJWCVle_1b2I3VRWFNb4MLMcAnMVXeHH5lwR8ZXngHBoKhNsNlGDtxAQEYjlzPlOBaI0IcSN4AO_T7S0LPYZRHuZMAVLbk0DlaDB8WO9-TVSyN0ac7b8o3oRf-C6moZgcTtwC0SeDSvki-pNFy3WXDujQcz1Isa27fPJd_U5X2A" -H "Content-Type: application/json" -d "{ "start": "2019-05-20T10:00:00.000Z", "end": "2019-05-25T10:00:00.000Z", "event": "Conversation-Group-Assigned", "format": "csv"}"
EXPAND ↓
Response

A successful request returns 202 along with the reports response object.

Response object 
1
2
3
4
5
6
7
{
    "id": "1ac520cf-b1a4-4741-8b01-e383563ae402",
    "link": {
        "rel": "extracts",
        "href": "/reports/raw/"1ac520cf-b1a4-4741-8b01-e383563ae402”
    }
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Unique identifier for the requested report. This is an auto-generated value. In further API requests, you can use this value to identify and retrieve the URL to a report.
link link object Reference to the requested report.
Attributes of the link object
Attribute Name Data Type Description
rel string Type of link relationship between the resource accessed by the href URL and the source from which the resource is referenced.
href string Reference or URL to access the requested report.

Retrieve a report

Identifies a report by the id passed in the request and returns the links containing the location and status of the requested report.

get
/reports/raw/{id}
Query parameters

You can use the following query parameter to filter the bulk response data.

Parameter Name Description Example
status Limits the response to conversation objects whose status value matches the parameter value.
Valid values: COMPLETED, PENDING, FAILED

GET /reports/raw/{id}?status=COMPLETED
Path parameters
Parameter Name Data Type Description
id string Unique identifier for the requested report.
Sample request | Curl
Copied Copy 
1
curl -X GET "https://api.freshchat.com/v2/reports/raw/1ac520cf-b1a4-4741-8b01-e383563ae402" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpS216TTVkenRIWmprdmdSY3VrVHgxTzJ2SFlTM0U5YmVJME9XbXRNR1ZzIn0.eyJqdGkiOiIyYTJiNTAwNi04NDk2LTQyMDctYWUyOC1mYzY4MTI4MGRkMmEiLCJleHAiOjE5MDM5Mzg1MTYsIm5iZiI6MCwiaWF0IjoxNTg4NTc4NTE2LCJpc3MiOiJodHRwOi8vaW50ZXJuYWwtZmMtdXNlMS0wMC1rZXljbG9hay1vYXV0aC0xMzA3MzU3NDU5LnVzLWVhc3QtMS5lbGIuYW1hem9uYXdzLmNvbS9hdXRoL3JlYWxtcy9wcm9kdWN0aW9uIiwiYXVkIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwic3ViIjoiN2VlYTUzNzctYzEzNy00MDI1LWFlYzgtMDhmZjE4MzkwN2EyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMjMyOTcwOWMtMTVjZS00NzA5LWE1MDctZjcwNGRmNmNmOTFmIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6W10sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJhZ2VudDp1cGRhdGUgbWVzc2FnZTpjcmVhdGUgYWdlbnQ6Y3JlYXRlIG1lc3NhZ2U6Z2V0IGRhc2hib2FyZDpyZWFkIHJlcG9ydHM6ZXh0cmFjdDpyZWFkIHJlcG9ydHM6cmVhZCBhZ2VudDpyZWFkIGNvbnZlcnNhdGlvbjp1cGRhdGUgdXNlcjpkZWxldGUgY29udmVyc2F0aW9uOmNyZWF0ZSBvdXRib3VuZG1lc3NhZ2U6Z2V0IG91dGJvdW5kbWVzc2FnZTpzZW5kIHVzZXI6Y3JlYXRlIHJlcG9ydHM6ZmV0Y2ggdXNlcjp1cGRhdGUgdXNlcjpyZWFkIHJlcG9ydHM6ZXh0cmFjdCBjb252ZXJzYXRpb246cmVhZCIsImNsaWVudElkIjoiOTViZTBkYmEtOWE0ZS00ZjIyLWJmMDYtMjkxMjI4MjVjOWRhIiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguMTI5LjE1NyIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjEyOS4xNTcifQ.wE6Kec6OYhsD-CfW2YKf1XsIfGXhXMBZdlZuuACJ8HPukABaNRS3iMDmv0scPdIJJGKmN0w1_DIPQSwiigeA3Xb5NTVOFIKniICVMIwoBMcmeo3njJa4kFwkIo6dD-29xOG5B2flv9F-Nw0jX9qZ-G6oVRvYUS6Ra4-MISLIbe6qJWCVle_1b2I3VRWFNb4MLMcAnMVXeHH5lwR8ZXngHBoKhNsNlGDtxAQEYjlzPlOBaI0IcSN4AO_T7S0LPYZRHuZMAVLbk0DlaDB8WO9-TVSyN0ac7b8o3oRf-C6moZgcTtwC0SeDSvki-pNFy3WXDujQcz1Isa27fPJd_U5X2A"
EXPAND ↓
Response

A successful request returns 200 along with the links of the requested reports, as an array

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "id": "unique_id",
    "status": "COMPLETED",
    "interval": "2020-01-23 00:30:00.0 2020-01-23 18:59:59.0",
    "links": [
        {
            "link": {
                "rel": "extraction",
                "href": "private_s3_url"
            },
            "from_date": "2020-01-23T00:30:00.000Z",
            "to_date": "2020-01-23T18:59:59.000Z",
            "status": "COMPLETED"
        }
    ]
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id string Unique identifier for the requested report.
status string Status of the requested report.
Possible values:
PENDING - Report generation is in progress.
FAILED - Report generation has failed.
COMPLETED - Report generation is complete.
interval string Time period for which the report is generated.
links array of reports link objects List of URLs that point to the location of the requested report. The requested report is split into sub-reports according to the interval attribute. The lifespan of the links is one hour.
Attributes of the reports link object:
link object: Location of the requested report.
from (string): Starting date of the sub-report generation, specified in the UTC format.
to (string): Ending date of the sub-report generation, specified in the UTC format.
status(string): Status of the sub-report.
Possible values:
PENDING - Sub-report generation is in progress.
FAILED - Sub-report generation has failed.
COMPLETED - Sub-report generation is complete.

Metrics

Through a live UI dashboard, Freshchat provides a mechanism to view the real-time summary (metrics) of activities in a Freshchat account. You can use the metrics APIs to retrieve the dashboard metrics for further analysis and processing. You can retrieve,

  • Instant metrics: Metrics at the current instant. For the list of metrics that can be retrieved under this category, see Instant metrics.
  • Historical metrics: Metrics accurate up to five minutes before the current instant. For the list of metrics that can be retrieved under this category, see Historical metrics.

Endpoints

GET /metrics/historical
GET /metrics/instant

Retrieve historical metrics

Retrieves historical metrics based on the retrieval criteria specified through query parameters.

get
/v2/metrics/historical
Query parameters

You can use a combination of the following query parameters to retrieve the appropriate historical metric. Ensure that the query parameter values are URL encoded.

Parameter Name Description
metricMandatory Name of the metric to be retrieved.
For a list of valid values and metrics definition, see Historic metrics.
startMandatory
Should be a date-time value specified in the UTC format.		 Starting date of the time period for which the metric is to be retrieved.
endMandatory
Should be a date-time value specified in the UTC format.		 Ending date of the time period for which the metric is to be retrieved.
interval

Frequency at which the metrics are retrieved.
In an API call, the retrieval time period is specified through the start and end parameter values. If there is an interval specified, the time period is broken down into subsets based on the interval value and the metric is retrieved for each subset.
For example, for a time period of one month, if the interval is 1w (1 week), the retrieved metrics contains four values - one for each week.

Valid values: 1m, 5m, 15m, 1h, 1d, 1w, 1mo
aggregatorMandatory for aggregate metrics
Note: Ensure not to pass an aggregator value for count metrics.

Metrics can be count or aggregate metrics. Count metrics sum the number of metric values in the specified time period. For example, if the time period spans a month and the metric is conversation_metrics.resolved_interactions, an API call to retrieve this metric returns the number of resolved interactions in the month. Aggregate metrics summarize the atomic metrics values over the specified time period. For example, if the time period spans a month and the metric is conversation_metrics.wait_time, an API call to retrieve this metric returns the aggregated (mean) wait time for all incoming conversations, in the month.
aggregator parameter value is the method used to summarize (find mean value of ) atomic metrics.

Valid values:
  • min: The minimum of all values in the specified time period.
  • max: The maximum of all values in the specified time period.
  • avg: The mean value is calculated by finding the sum of all values in the data set and dividing the result by the total number of values in the data set.
  • median: The mean value is calculated by sorting the values in the data set, in ascending or descending order and finding the middle value.
  • p90: The mean value is calculated by sorting the values in the data set, in ascending order and finding the lowest value that is greater than 90% of the values.
Ensure to specify an aggregator value only for aggregate metrics. For the list of aggregate and count metrics, see Historical metrics.
x_timeMandatory for conversation_metrics.assigned_x_mins_ago_and_not_replied_to, conversation_metrics.created_x_mins_ago_and_unassigned, and conversation_metrics

For certain metrics, the retrieval calls do not consider the time period specified through start and end values. These calls act like instant metric calls and consider a combination of the current instant and the x_time value, to retrieve the appropriate metrics. These calls retrieve the metrics in the time period spanning x-minutes-from-the-current-instant to the current instant.
x_time value is the value of the “x minutes”.

Note: start and end are mandatory parameters. So, ensure to specify a value with the valid format for start and end even when retrieving metrics that are only dependent on x_time.
Grouping and filtering metrics values
When retrieving the historical metrics, you can specify an appropriate group_by parameter value and retrieve historical metrics group-wise or agent-wise.
Notes:
  1. The csat_metrics.rating metric can additionally be retrieved rating-wise. For example, if the group_by value for this metric is rating, the API call retrieves the number of CSAT surveys under each of the five possible ratings - that is, number of CSATs that have returned with a rating of 5, number of CSATs that have returned with a rating of 4, and so on.
  2. The conversation_metrics.created_interactions is an account-level metric and cannot be retrieved group-wise or agent-wise. For this metric, if you try to run an API call with the group_by query param value as group, agent, or rating, the call fails.

You can use the filter_by query parameter to filter the (group-wise or agent-wise) retrieved metrics and view only a subset of the results.
For the valid group_by and filter_by values for each metric, see Historic metrics.
group_by Grouping criteria for the metrics. Metrics can be organized based on groups or agents configured in the Freshchat system or based on rating for csat_metrics.rating metrics.
Valid values: group, agent, rating
filter_by Filtering criteria for retrieved metrics. Bulk retrieved metrics can be filtered by agents or groups, specified as valid agent.id or group.id.
For example, to filter the metrics by the groups identifiers, group_id_1 and group_id_2, the filter_by parameter value must be in the format group=group_id_1,group=group_id_2
Note: In the following API request samples, all query parameter values are URL encoded. For example, the filter_by parameter value of the format group=group_id_1,group=group_id_2 is URL encoded as group%3Dgroup_id_1%2Cgroup%3Dgroup_id_2.
Example 1:
To retrieve the csat_metrics.count_per_rating metric, aggregated by the average method of finding mean value, filtered for two groups with ids - c7e65b1f-a360-4154-87a6-951b1967dd15 and 713834e0-d031-4aee-90d8-fadcb0bbfa47

GET /metrics/historical?metric=csat_metrics.count_per_rating&start=2022-01-01T10:00:00.000Z&end=2022-11-01T10:00:00.000Z&aggregator=avg&filter_by=group%3Dc7e65b1f-a360-4154-87a6-951b1967dd15%2Cgroup%3D713834e0-d031-4aee-90d8-fadcb0bbfa47

Example 2:
To perform a group-wise retrieval of the team_performance.responses_sent metric and filter the retrieved data for two groups with ids - c7e65b1f-a360-4154-87a6-951b1967dd15 and 713834e0-d031-4aee-90d8-fadcb0bbfa47

GET /metrics/historical?metric=team_performance.responses_sent&start=2022-01-01T10:00:00.000Z&end=2022-11-01T10:00:00.000Z&filter_by=group%3Dc7e65b1f-a360-4154-87a6-951b1967dd15%2Cgroup%3D713834e0-d031-4aee-90d8-fadcb0bbfa47&group_by=group

Example 3:
To perform an agent-wise retrieval of the team_performance.first_response_time metric and filter the retrieved data for two agents with ids - 9a463df8-9655-4d44-a9e3-eda9d6ec89f2 and 1de5d130-1c62-48cf-8349-1b39c60d0c28

GET /metrics/historical?metric=team_performance.first_response_time&start=2022-01-01T10:00:00.000Z&end=2022-11-01T10:00:00.000Z&aggregator=avg&filter_by=agent%3D9a463df8-9655-4d44-a9e3-eda9d6ec89f2%2Cagent%3D1de5d130-1c62-48cf-8349-1b39c60d0c28&group_by=agent

Example 4:
To perform a group-wise retrieval of the conversation_metrics.assigned_interactions metric and filter the retrieved data for two agents with ids - 6e7a0d23-bbd4-45ff-87b2-b46c339050f7 and 1de5d130-1c62-48cf-8349-1b39c60d0c28

GET /metric=conversation_metrics.assigned_interactions&start=2022-11-01T10:00:00.000Z&end=2022-11-20T10:00:00.000Z&group_by=group&filter_by=agent%3D1de5d130-1c62-48cf-8349-1b39c60d0c28%2Cagent%3D6e7a0d23-bbd4-45ff-87b2-b46c339050f7

Example 5:
To retrieve conversation_metrics.created_interactions metric for a time period of one month and interval of one week

GET /metrics/historical?metric=conversation_metrics.created_interactions&start=2022-10-01T10:00:00.000Z&end=2022-10-31T10:00:00.000Z&&interval=1w

Example 6:
To retrieve conversation_metrics.created_x_mins_ago_and_unassigned metric

GET /metrics/historical?metric=conversation_metrics.created_x_mins_ago_and_unassigned&start=2022-10-02T10:00:00.000Z&end=2022-11-04T10:00:00.000Z&x_time=17

Historical metrics
Valid value for metric_name and its description Aggregate or count metric Valid values for group_by Valid values for filter_by
csat_metrics:
A summary of the CSAT (Customer Satisfaction) survey ratings, within the specified time period. An API call to retrieve the csat_metrics lists all the following sub metrics and their corresponding values:
  • csat_metrics.satisfactory_interactions
  • csat_metrics.unsatisfactory_interactions
  • csat_metrics.total_rated_interactions
  • csat_metrics.count_per_rating: If an aggregator is not specified, the default aggregator is average.
 NA group or agent Any valid group.id or agent.id
csat_metrics.satisfactory_interactions:
A count of the number of satisfactory interactions recorded through CSAT surveys, within the specified time period.		 Count group or agent Any valid group.id or agent.id
csat_metrics.unsatisfactory_interactions:
A count of the number of unsatisfactory interactions recorded through CSAT surveys, within the specified time period.		 Count group or agent Any valid group.id or agent.id
csat_metrics.total_rated_interactions:
A count of the number of interactions that received a CSAT rating, within the specified time period.		 Count group or agent Any valid group.id or agent.id
csat_metrics.count_per_rating:
Average rating received in the specified time period.		 Aggregate group or agent Any valid group.id or agent.id
csat_metrics.rating:
A count of the number of CSAT surveys under each of the five possible ratings.		 Count group, agent, or rating Any valid group.id or agent.id
conversation_metrics.created_interactions:
A count of the number of interactions created for an account, in the Freshchat system, for the specified time period.		 Count NA
This is an account-level metric.
conversation_metrics:
A summary of all the conversation related metrics, within the specified time period. An API call to retrieve the conversation_metrics lists the following sub metrics and their corresponding values:
  • conversation_metrics.assigned_interactions
  • conversation_metrics.assigned_x_mins_ago_and_not_replied_to
  • conversation_metrics.created_x_mins_ago_and_unassigned
 Count group or agent Any valid group.id or agent.id
conversation_metrics.assigned_interactions:
A count of the number of interactions assigned to an agent or group, in the specified time period.

If the group_by value is group, the number of interactions assigned to each group is retrieved for all groups. The retrieved values are filtered by the group ids or agent ids specified in the filter_by value.

If the group_by value is agent, the number of interactions assigned to each agent is retrieved for all agents configured in the Freshchat system. The retrieved values are filtered by the group ids or agent ids specified in the filter_by value.		 Count group or agent Any valid group.id or agent.id
conversation_metrics.resolved_interactions:
A count of the number of interactions that a group or agent resolves, in the specified time periods.

If the group_by value is group, the number of interactions resolved by each group is retrieved for all groups. The retrieved values are filtered by the group ids or agent ids specified in the filter_by value.

If the group_by value is agent, the number of interactions resolved by each agent is retrieved for all agents configured in the Freshchat system. The retrieved values are filtered by the group ids or agent ids specified in the filter_by value.		 Count group or agent Any valid group.id or agent.id
conversation_metrics.assigned_x_mins_ago_and_not_replied_to:
A count of the number of conversations that were assigned to an agent or group x minutes from the current instant and are still pending a first response.

For retrieving this metric, you must provide a valid x_time value in the request. This specifies a value for the “x minutes”. For example, if x_time is 5, on retrieval, the conversation_metrics.assigned_x_mins_ago_and_not_replied_to value contains the count of conversations that were assigned to an agent or group five minutes before the current time and are still awaiting a response.

 Count group or agent Any valid group.id or agent.id
conversation_metrics.created_x_mins_ago_and_unassigned:
A count of the number of conversations that were created x minutes from the current instant and are still unassigned.
For retrieving this metric, you must provide a valid x_time value in the request. This specifies a value for the “x” minutes. For example, if x_time is 5, on retrieval, the conversation_metrics.created_x_mins_ago_and_unassigned value contains the count of conversations that were created five minutes before the current time and are still unassigned.		 Count group or agent Any valid group.id or agent.id
conversation_metrics.wait_time:
Average time a user has to wait before getting a response from the group or agent.		 Aggregate group or agent Any valid group.id or agent.id
team_performance: A summary of all performance related aggregate metrics, within the specified time period. An API call to retrieve the team_performance metrics lists the following sub metrics and their corresponding values:
  • team_performance.first_response_time
  • team_performance.response_time
  • team_performance.resolution_time
  • team_performance.wait_time: Average time a user has to wait before getting a response from the group or agent, after the conversation is assigned to a group or agent. This metric cannot be retrieved as an independent metric; it can only be retrieved as part of the team_performance metrics.
 Aggregate group or agent Any valid group.id or agent.id
team_performance.first_response_time:
Average time that a group or agent takes to send the first response to an assigned conversation.		 Aggregate group or agent Any valid group.id or agent.id.
team_performance.response_time:
Average time that a group or agent takes to send responses to an assigned conversation, after the first response.		 Aggregate group or agent Any valid group.id or agent.id
team_performance.resolution_time:
Average time that a group or agent takes to resolve an assigned conversation, from the time it is assigned.		 Aggregate group or agent Any valid group.id or agent.id
team_performance.responses_sent:
A count of the number of responses that the group or agent sends, in the specified time period.		 Count group or agent Any valid group.id or agent.id
team_performance.concurrency_ratio:
Average number of conversations that a group or agent handles simultaneously, in the specified time period.		 Aggregate group or agent Any valid group.id or agent.id
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/metrics/historical?metric=csat_metrics.count_per_rating&start=2022-03-08T10:00:00.000Z&end=2022-03-09T10:00:00.000Z&aggregator=avg&filter_by=group%3Dc7e65b1f-a360-4154-87a6-951b1967dd15%2Cgroup%3D713834e0-d031-4aee-90d8-fadcb0bbfa47&group_by=group&interval=1h" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJxxxdQ"
EXPAND ↓
Response

A successful request returns 200 OK along with the following response.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
    "metrics": [
        "csat_metrics.count_per_rating"
    ],
    "start": "2022-03-08T10:00:00.000Z",
    "end": "2022-03-09T10:00:00.000Z",
    "filters": {
        "metric_filters": [
            {
                "key": "group",
                "value": "c7e65b1f-a360-4154-87a6-951b1967dd15"
            },
            {
                "key": "group",
                "value": "713834e0-d031-4aee-90d8-fadcb0bbfa47"
            }
        ]
    },
    "aggregator": "avg",
    "interval": "1h",
    "data": [
        {
            "groupings": [
                {
                    "key": "group",
                    "value": "c7e65b1f-a360-4154-87a6-951b1967dd15"
                }
            ],
            "series": [
                {
                    "start": "2022-03-08T14:00:00.000Z",
                    "end": "2022-03-08T15:00:00.000Z",
                    "values": [{
                            "key": "csat_metrics.count_per_rating",
                            "value": "4.0"
                    }]
                }
            ]
        }
    ]
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
metrics array of strings Name of the retrieved metric.
start string Starting date of the time period for which the metric is retrieved, specified in the UTC format.
end string Ending date of the time period for which the metric is retrieved, specified in the UTC format.
filters object Details of the metric filter used to limit the retrieved metrics based on the specified group.ids or agent.ids.
Attributes of the object:
metric_filters (array of objects): Details of the metric filter, specified as a valid JSON object with two attributes:
  • key (string): Type of filter used.
    Possible values: group, agent
  • value (string): Identifier of the group or agent.
In the metric_filters array, there are as many objects as the number of ids used in the filter_by value.
aggregator string Method used to summarize the metrics. The attribute has a value only if the metric retrieved is an aggregate metric. For count metrics, aggregator is “ ”.
Possible values: min, max, avg, median, p90
interval string Frequency at which the metrics are retrieved.
Possible values: 1m, 5m, 15m, 1h, 1d, 1w, 1mo
data array of objects Grouping details based on which the metrics are retrieved and the corresponding metrics values.

Attributes of the object:
groupings (array of objects): When retrieving metrics, multiple combinations of grouping and filtering are possible. The groupings array contains the final grouping/filtering applied to the metrics during retrieval.

    Attributes of the object:
  • key (string): Type of grouping used when retrieving the metrics.
    Possible values: group, agent, rating
  • value (string): Further values by which the metrics are filtered. If no filter_by value is specified during retrieval, value is null.

series (array of objects): The retrieved metrics and the corresponding time period. Each array element represents an interval of the entire time period.

    Attributes of the object:
  • start (string): Starting date of the interval for which the metric is retrieved, specified in the UTC format.
  • end (string): Ending date of the interval for which the metric is retrieved, specified in the UTC format.
  • values (array of objects): Details of the metrics, specified as a valid JSON object of key (name of the metric) -value (actual value of the metric).

Retrieve instant metrics

Retrieves instant metrics based on the retrieval criteria specified through query parameters.

get
/v2/metrics/instant
Query parameters

You can use a combination of the following query parameters to retrieve the appropriate instant metric. Ensure that the query parameter values are URL encoded.

Parameter Name Description
metricMandatory Name of the metric to be retrieved.
For a list of valid values and metrics definition, see Instant metrics.
group_by Grouping criteria for the metrics. When retrieving the instant metrics, you can specify an appropriate group_by parameter value and retrieve instant metrics organized group-wise.
Valid value: group
filter_by Filtering criteria for the metrics. You can use the filter_by query parameter to filter the (group-wise) retrieved metrics and view only a subset of the results.
For example, to filter the metrics by the groups identifiers, group_id_1 and group_id_2, the filter_by parameter value must be in the format group=group_id_1,group=group_id_2.
Valid value: Any valid group.id(s).
summary Specifies whether the retrieved values are to be presented as a summary or as a detailed list. If summary is true, the response contains only the count of agents in each group. If summary is false, the response also includes the corresponding agent.ids.
Valid values: true, false
Example
Note: In the following API request sample, the query parameter values are URL encoded. For example, the filter_by parameter value of the format group=group_id_1,group=group_id_2 is URL encoded as group%3Dgroup_id_1%2Cgroup%3Dgroup_id_2.

To retrieve the team_presence.online metric, organized based on groups, summarized, and, filtered for two group IDs - 601b70f2-435f-4232-8db2-7cde8e4bda86 and 7c6ec228-023d-4142-9c7b-0d42c06c1154

GET /metrics/instant?metric=team_presense.online&filter_by=group%3D601b70f2-435f-4232-8db2-7cde8e4bda86%2Cgroup%3D7c6ec228-023d-4142-9c7b-0d42c06c1154&group_by=group&summary=true
Instant metrics
Valid value for metric Description
team_presence.online A count of the number of agents who are online, at the instant when the metric is being retrieved.
team_presence.offline A count of the number of agents who are offline, at the instant when the metric is being retrieved.
team_presence.active_on_intelliassign A count of the number of agents who are active for IntelliAssign, at the instant when the metric is being retrieved.
team_presence.inactive_on_intelliassign A count of the number of online agents who are inactive on IntelliAssign, at the instant when the metric is being retrieved.
team_presence.total_members A count of the total number of agents in the Freshchat system (online and offline), at the instant when the metric is being retrieved.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/metrics/instant?metric=team_presence.online&filter_by=group%3D388c61d3-d564-4b55-a650-38dd3c287f21%2Cgroup%3Dbfdc3b66-6de3-4124-b8b7-c37059087d88&group_by=group&summary=false" 
        -H "accept: application/json" 
        -H "Authorization: Bearer eyJxxxUIV4"
EXPAND ↓
Response

A successful request returns 200 OK along with the following response.

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
    "metric": "team_presence.online",
    "filters": {
        "metric_filters": [{
                "key": "group",
                "value": "bfdc3b66-6de3-4124-b8b7-c37059087d88"
            },
            {
                "key": "group",
                "value": "388c61d3-d564-4b55-a650-38dd3c287f21"
            }
        ]
    },
    "data": [{
            "groupings": [{
                    "key": "group",
                    "value": "bfdc3b66-6de3-4124-b8b7-c37059087d88"
                }],
            "values": [{
                    "key": "team_presence.online",
                    "resources": [{
                        "id": "1de5d130-1c62-48cf-8349-1b39c60d0c28"
                    }],
                    "count": 1
                }]
        },
        {
            "groupings": [{
                    "key": "group",
                    "value": "388c61d3-d564-4b55-a650-38dd3c287f21"
                }],
            "values": [{
                    "key": "team_presence.online",
                    "resources": [{
                        "id": "1de5d130-1c62-48cf-8349-1b39c60d0c28"
                    }],
                    "count": 1
                }
            ]
        }
    ]
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
metric string Name of the retrieved metric.
filters object Details of the metric filters used to limit the retrieved metrics based on the specified group.ids.
Attributes of the object:
metric_filters (array of objects): Details of the metric filter, specified as a valid JSON object with two attributes:
  • key (string): Type of filter used. For now, it is always group.
  • value (string): Identifier of the group.
In the metric_filters array, there are as many objects as the number of ids used in the filter_by value.
data array of objects Grouping details based on which the metrics are retrieved and the corresponding metrics values.

Attributes of the object:
Note: There are as many objects as the number of ids used in the filter_by value.
groupings (array of objects): When retrieving metrics, a combination of grouping and filtering is applied. The groupings array contains the final grouping/filtering applied to the metrics during retrieval.

    Attributes of the object:
  • key (string): Type of grouping used when retrieving the metrics.
    Possible value: group
  • value (string): Identifier of the group.

values (array of objects): Details of the retrieved metric.

    Attributes of the object:
  • key (string): Name of the metric.
  • resources (array of strings): Identifiers of the agents who satisfy the specified metric, if during retrieval summary is set as false. The resources array is empty if summary was set to true or the count value is 0.
  • count (integer): Number of agents who satisfy the specified metric.

Business Hours

Business hours convey the working hours of a group. If business hours are configured for a group, conversations can be assigned to the group only during the specified business hours.

Endpoint

GET /business-hours/within-bh

Verify whether a group is within business hours

Identifies a group by the group_id specified (as a query parameter value) and returns a boolean response specifying whether the group is within business hours.

get
/v2/business-hours/within-bh
Query parameters
Parameter Name Data Type Description
group_id string Identifier of the group, auto-generated when a group is configured in the Freshchat system.
Note: If no group_id is specified, the API call returns a default response.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account>.freshchat.com/v2/business-hours/within-bh?group_id=e71aa24a-3ec8-4ddb-93db-bc32d8afded1" 
-H "accept: application/json" 
-H "Authorization: Bearer eyashV4"
EXPAND ↓
Response

A successful request returns 200 OK along with a boolean verification.

Example 
1
2
3
{
    "with_in_business_hours": false
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
with_in_business_hours boolean Specifies whether the group is within the business hours at the instant when the group’s business hours is verified.
Possible values: true, false
Default value: true
Note: If business hours are not configured for the group or if the group.id isn’t added to the request, the API call returns the default value.